From 6504f7fe43e9264a110527374f4bbe20f8e0004d Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 10:04:28 +0200 Subject: Adding upstream version 2:2.6.1. Signed-off-by: Daniel Baumann --- docs/ChangeLog.old | 887 +++++++++++++++++++++++++++++++++++++++ docs/Keyring.txt | 56 +++ docs/LUKS2-locking.txt | 61 +++ docs/doxyfile | 335 +++++++++++++++ docs/doxygen_index.h | 110 +++++ docs/examples/Makefile | 17 + docs/examples/crypt_log_usage.c | 94 +++++ docs/examples/crypt_luks_usage.c | 250 +++++++++++ docs/on-disk-format-luks2.pdf | Bin 0 -> 382277 bytes docs/on-disk-format.pdf | Bin 0 -> 119729 bytes docs/v1.0.7-ReleaseNotes | 92 ++++ docs/v1.1.0-ReleaseNotes | 110 +++++ docs/v1.1.1-ReleaseNotes | 47 +++ docs/v1.1.2-ReleaseNotes | 33 ++ docs/v1.1.3-ReleaseNotes | 13 + docs/v1.2.0-ReleaseNotes | 126 ++++++ docs/v1.3.0-ReleaseNotes | 101 +++++ docs/v1.3.1-ReleaseNotes | 14 + docs/v1.4.0-ReleaseNotes | 131 ++++++ docs/v1.4.1-ReleaseNotes | 25 ++ docs/v1.4.2-ReleaseNotes | 44 ++ docs/v1.4.3-ReleaseNotes | 62 +++ docs/v1.5.0-ReleaseNotes | 241 +++++++++++ docs/v1.5.1-ReleaseNotes | 32 ++ docs/v1.6.0-ReleaseNotes | 261 ++++++++++++ docs/v1.6.1-ReleaseNotes | 32 ++ docs/v1.6.2-ReleaseNotes | 25 ++ docs/v1.6.3-ReleaseNotes | 50 +++ docs/v1.6.4-ReleaseNotes | 57 +++ docs/v1.6.5-ReleaseNotes | 54 +++ docs/v1.6.6-ReleaseNotes | 29 ++ docs/v1.6.7-ReleaseNotes | 84 ++++ docs/v1.6.8-ReleaseNotes | 47 +++ docs/v1.7.0-ReleaseNotes | 81 ++++ docs/v1.7.1-ReleaseNotes | 36 ++ docs/v1.7.2-ReleaseNotes | 37 ++ docs/v1.7.3-ReleaseNotes | 20 + docs/v1.7.4-ReleaseNotes | 22 + docs/v1.7.5-ReleaseNotes | 22 + docs/v2.0.0-ReleaseNotes | 605 ++++++++++++++++++++++++++ docs/v2.0.1-ReleaseNotes | 109 +++++ docs/v2.0.2-ReleaseNotes | 93 ++++ docs/v2.0.3-ReleaseNotes | 121 ++++++ docs/v2.0.4-ReleaseNotes | 119 ++++++ docs/v2.0.5-ReleaseNotes | 102 +++++ docs/v2.0.6-ReleaseNotes | 97 +++++ docs/v2.1.0-ReleaseNotes | 210 +++++++++ docs/v2.2.0-ReleaseNotes | 279 ++++++++++++ docs/v2.2.1-ReleaseNotes | 36 ++ docs/v2.2.2-ReleaseNotes | 56 +++ docs/v2.3.0-ReleaseNotes | 209 +++++++++ docs/v2.3.1-ReleaseNotes | 45 ++ docs/v2.3.2-ReleaseNotes | 42 ++ docs/v2.3.3-ReleaseNotes | 42 ++ docs/v2.3.4-ReleaseNotes | 112 +++++ docs/v2.3.5-ReleaseNotes | 181 ++++++++ docs/v2.3.6-ReleaseNotes | 56 +++ docs/v2.4.0-ReleaseNotes | 302 +++++++++++++ docs/v2.4.1-ReleaseNotes | 47 +++ docs/v2.4.2-ReleaseNotes | 37 ++ docs/v2.4.3-ReleaseNotes | 101 +++++ docs/v2.5.0-ReleaseNotes | 291 +++++++++++++ docs/v2.6.0-ReleaseNotes | 236 +++++++++++ docs/v2.6.1-ReleaseNotes | 50 +++ 64 files changed, 7316 insertions(+) create mode 100644 docs/ChangeLog.old create mode 100644 docs/Keyring.txt create mode 100644 docs/LUKS2-locking.txt create mode 100644 docs/doxyfile create mode 100644 docs/doxygen_index.h create mode 100644 docs/examples/Makefile create mode 100644 docs/examples/crypt_log_usage.c create mode 100644 docs/examples/crypt_luks_usage.c create mode 100644 docs/on-disk-format-luks2.pdf create mode 100644 docs/on-disk-format.pdf create mode 100644 docs/v1.0.7-ReleaseNotes create mode 100644 docs/v1.1.0-ReleaseNotes create mode 100644 docs/v1.1.1-ReleaseNotes create mode 100644 docs/v1.1.2-ReleaseNotes create mode 100644 docs/v1.1.3-ReleaseNotes create mode 100644 docs/v1.2.0-ReleaseNotes create mode 100644 docs/v1.3.0-ReleaseNotes create mode 100644 docs/v1.3.1-ReleaseNotes create mode 100644 docs/v1.4.0-ReleaseNotes create mode 100644 docs/v1.4.1-ReleaseNotes create mode 100644 docs/v1.4.2-ReleaseNotes create mode 100644 docs/v1.4.3-ReleaseNotes create mode 100644 docs/v1.5.0-ReleaseNotes create mode 100644 docs/v1.5.1-ReleaseNotes create mode 100644 docs/v1.6.0-ReleaseNotes create mode 100644 docs/v1.6.1-ReleaseNotes create mode 100644 docs/v1.6.2-ReleaseNotes create mode 100644 docs/v1.6.3-ReleaseNotes create mode 100644 docs/v1.6.4-ReleaseNotes create mode 100644 docs/v1.6.5-ReleaseNotes create mode 100644 docs/v1.6.6-ReleaseNotes create mode 100644 docs/v1.6.7-ReleaseNotes create mode 100644 docs/v1.6.8-ReleaseNotes create mode 100644 docs/v1.7.0-ReleaseNotes create mode 100644 docs/v1.7.1-ReleaseNotes create mode 100644 docs/v1.7.2-ReleaseNotes create mode 100644 docs/v1.7.3-ReleaseNotes create mode 100644 docs/v1.7.4-ReleaseNotes create mode 100644 docs/v1.7.5-ReleaseNotes create mode 100644 docs/v2.0.0-ReleaseNotes create mode 100644 docs/v2.0.1-ReleaseNotes create mode 100644 docs/v2.0.2-ReleaseNotes create mode 100644 docs/v2.0.3-ReleaseNotes create mode 100644 docs/v2.0.4-ReleaseNotes create mode 100644 docs/v2.0.5-ReleaseNotes create mode 100644 docs/v2.0.6-ReleaseNotes create mode 100644 docs/v2.1.0-ReleaseNotes create mode 100644 docs/v2.2.0-ReleaseNotes create mode 100644 docs/v2.2.1-ReleaseNotes create mode 100644 docs/v2.2.2-ReleaseNotes create mode 100644 docs/v2.3.0-ReleaseNotes create mode 100644 docs/v2.3.1-ReleaseNotes create mode 100644 docs/v2.3.2-ReleaseNotes create mode 100644 docs/v2.3.3-ReleaseNotes create mode 100644 docs/v2.3.4-ReleaseNotes create mode 100644 docs/v2.3.5-ReleaseNotes create mode 100644 docs/v2.3.6-ReleaseNotes create mode 100644 docs/v2.4.0-ReleaseNotes create mode 100644 docs/v2.4.1-ReleaseNotes create mode 100644 docs/v2.4.2-ReleaseNotes create mode 100644 docs/v2.4.3-ReleaseNotes create mode 100644 docs/v2.5.0-ReleaseNotes create mode 100644 docs/v2.6.0-ReleaseNotes create mode 100644 docs/v2.6.1-ReleaseNotes (limited to 'docs') diff --git a/docs/ChangeLog.old b/docs/ChangeLog.old new file mode 100644 index 0000000..516ea17 --- /dev/null +++ b/docs/ChangeLog.old @@ -0,0 +1,887 @@ +2012-12-21 Milan Broz + * Since version 1.6 This file is no longer maintained. + * See version control log http://code.google.com/p/cryptsetup/source/list + +2012-10-11 Milan Broz + * Added keyslot checker (by Arno Wagner). + * Version 1.5.1. + +2012-09-11 Milan Broz + * Add crypt_keyslot_area() API call. + +2012-08-27 Milan Broz + * Optimize seek to keyfile-offset (Issue #135, thx to dreisner). + * Fix luksHeaderBackup for very old v1.0 unaligned LUKS headers. + +2012-08-12 Milan Broz + * Allocate loop device late (only when real block device needed). + * Rework underlying device/file access functions. + * Create hash image if doesn't exist in veritysetup format. + * Provide better error message if running as non-root user (device-mapper, loop). + +2012-07-10 Milan Broz + * Version 1.5.0. + +2012-06-25 Milan Broz + * Add --device-size option for reencryption tool. + * Switch to use unit suffix for --reduce-device-size option. + * Remove open device debugging feature (no longer needed). + * Fix library name for FIPS check. + +2012-06-20 Milan Broz + * Version 1.5.0-rc2. + +2012-06-18 Milan Broz + * Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool. + * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID). + * Add --test-passphrase option for luksOpen (check passphrase only). + +2012-06-11 Milan Broz + * Introduce veritysetup for dm-verity target management. + * Version 1.5.0-rc1. + +2012-06-10 Milan Broz + * Both data and header device can now be a file. + * Loop is automatically allocated in crypt_set_data_device(). + * Require only up to last keyslot area for header device (ignore data offset). + * Fix header backup and restore to work on files with large data offset. + +2012-05-27 Milan Broz + * Fix readonly activation if underlying device is readonly (1.4.0). + * Include stddef.h in libdevmapper.h (size_t definition). + * Version 1.4.3. + +2012-05-21 Milan Broz + * Add --enable-fips for linking with fipscheck library. + * Initialize binary and library selfcheck if running in FIPS mode. + * Use FIPS RNG in FIPS mode for KEY and SALT (only gcrypt backend supported). + +2012-05-09 Milan Broz + * Fix keyslot removal (wipe keyslot) for device with 4k hw block (1.4.0). + * Allow empty cipher (cipher_null) for testing. + +2012-05-02 Milan Broz + * Fix loop mapping on readonly file. + * Relax --shared test, allow mapping even for overlapping segments. + * Support shared flag for LUKS devices (dangerous). + * Switch on retry on device remove for libdevmapper. + * Allow "private" activation (skip some udev global rules) flag. + +2012-04-09 Milan Broz + * Fix header check to support old (cryptsetup 1.0.0) header alignment. (1.4.0) + * Version 1.4.2. + +2012-03-16 Milan Broz + * Add --keyfile-offset and --new-keyfile-offset parameters to API and CLI. + * Add repair command and crypt_repair() for known LUKS metadata problems repair. + * Allow one to specify --align-payload only for luksFormat. + +2012-03-16 Milan Broz + * Unify password verification option. + * Support password verification with quiet flag if possible. (1.2.0) + * Fix retry if entered passphrases (with verify option) do not match. + * Support UUID= format for device specification. + +2012-02-11 Milan Broz + * Add --master-key-file option to luksOpen (open using volume key). + +2012-01-12 Milan Broz + * Fix use of empty keyfile. + +2011-11-13 Milan Broz + * Fix error message for luksClose and detached LUKS header. + * Allow --header for status command to get full info with detached header. + +2011-11-09 Milan Broz + * Version 1.4.1. + +2011-11-05 Milan Broz + * Merge pycryptsetup (Python libcryptsetup bindings). + * Fix stupid typo in set_iteration_time API call. + * Fix cryptsetup status output if parameter is device path. + +2011-10-27 Milan Broz + * Fix crypt_get_volume_key_size() for plain device. + * Fix FSF address in license text. + +2011-10-25 Milan Broz + * Print informative message in isLuks only in verbose mode. + * Version 1.4.0. + +2011-10-10 Milan Broz + * Version 1.4.0-rc1. + +2011-10-05 Milan Broz + * Support Nettle 2.4 crypto backend (for ripemd160). + * If device is not rotational, do not use Gutmann wipe method. + * Add crypt_last_error() API call. + * Fix luksKillSLot exit code if slot is inactive or invalid. + * Fix exit code if passphrases do not match in luksAddKey. + * Add LUKS on-disk format description into package. + +2011-09-22 Milan Broz + * Support key-slot option for luksOpen (use only explicit keyslot). + +2011-08-22 Milan Broz + * Add more paranoid checks for LUKS header and keyslot attributes. + * Fix crypt_load to properly check device size. + * Use new /dev/loop-control (kernel 3.1) if possible. + * Enhance check of device size before writing LUKS header. + * Do not allow context format of already formatted device. + +2011-07-25 Milan Broz + * Remove hash/hmac restart from crypto backend and make it part of hash/hmac final. + * Improve check for invalid offset and size values. + +2011-07-19 Milan Broz + * Revert default initialisation of volume key in crypt_init_by_name(). + * Do not allow key retrieval while suspended (key could be wiped). + * Do not allow suspend for non-LUKS devices. + * Support retries and timeout parameters for luksSuspend. + * Add --header option for detached metadata (on-disk LUKS header) device. + * Add crypt_init_by_name_and_header() and crypt_set_data_device() to API. + * Allow different data offset setting for detached header. + +2011-07-07 Milan Broz + * Remove old API functions (all functions using crypt_options). + * Add --enable-discards option to allow discards/TRIM requests. + * Add crypt_get_iv_offset() function to API. + +2011-07-01 Milan Broz + * Add --shared option for creating non-overlapping crypt segments. + * Add shared flag to libcryptsetup api. + * Fix plain crypt format parameters to include size option (API change). + +2011-06-08 Milan Broz + * Fix return code for status command when device doesn't exists. + +2011-05-24 Milan Broz + * Version 1.3.1. + +2011-05-17 Milan Broz + * Fix keyfile=- processing in create command (1.3.0). + * Simplify device path status check. + +2011-05-03 Milan Broz + * Do not ignore size argument for create command (1.2.0). + +2011-04-18 Milan Broz + * Fix error paths in blockwise code and lseek_write call. + * Add Nettle crypto backend support. + +2011-04-05 Milan Broz + * Version 1.3.0. + +2011-03-22 Milan Broz + * Also support --skip and --hash option for loopaesOpen. + * Fix return code when passphrase is read from pipe. + * Document cryptsetup exit codes. + +2011-03-18 Milan Broz + * Respect maximum keyfile size parameter. + * Introduce maximum default keyfile size, add configure option. + * Require the whole key read from keyfile in create command (broken in 1.2.0). + * Fix offset option for loopaesOpen. + * Lock memory also in luksDump command. + * Version 1.3.0-rc2. + +2011-03-14 Milan Broz + * Version 1.3.0-rc1. + +2011-03-11 Milan Broz + * Add loop manipulation code and support mapping of images in file. + * Add backing device loop info into status message. + * Add luksChangeKey command. + +2011-03-05 Milan Broz + * Add exception to COPYING for binary distribution linked with OpenSSL library. + * Set secure data flag (wipe all ioctl buffers) if devmapper library supports it. + +2011-01-29 Milan Broz + * Fix mapping removal if device disappeared but node still exists. + * Fix luksAddKey return code if master key is used. + +2011-01-25 Milan Broz + * Add loop-AES handling (loopaesOpen and loopaesClose commands). + (requires kernel 2.6.38 and above) + +2011-01-05 Milan Broz + * Fix static build (--disable-static-cryptsetup now works properly). + +2010-12-30 Milan Broz + * Add compile time crypto backends implementation + (gcrypt, OpenSSL, NSS and userspace Linux kernel crypto api). + * Currently NSS is lacking ripemd160, cannot provide full plain compatibility. + * Use --with-crypto_backend=[gcrypt|openssl|nss|kernel] to configure. + +2010-12-20 Milan Broz + * Version 1.2.0. + +2010-11-25 Milan Broz + * Fix crypt_activate_by_keyfile() to work with PLAIN devices. + * Fix create command to properly handle keyfile size. + +2010-11-16 Milan Broz + * Version 1.2.0-rc1. + +2010-11-13 Milan Broz + * Fix password callback call. + * Fix default plain password entry from terminal in activate_by_passphrase. + * Add --dump-master-key option for luksDump to allow volume key dump. + * Allow one to activate by internally cached volume key + (format/activate without keyslots active - used for temporary devices). + * Initialize volume key from active device in crypt_init_by_name() + * Fix cryptsetup binary exitcodes. + * Increase library version (still binary compatible with 1.1.x release). + +2010-11-01 Milan Broz + * No longer support luksDelKey, reload and --non-exclusive. + * Remove some obsolete info from man page. + * Add crypt_get_type(), crypt_resize(), crypt_keyslot_max() + and crypt_get_active_device() to API. + * Rewrite all implementations in cryptsetup to new API. + * Fix luksRemoveKey to behave as documented (do not ask + for remaining keyslot passphrase). + * Add more regression tests for commands. + * Disallow mapping of device which is already in use (mapped or mounted). + * Disallow luksFormat on device in use. + +2010-10-27 Milan Broz + * Rewrite cryptsetup luksFormat, luksOpen, luksAddKey to use new API + to allow adding new features. + * Implement --use-random and --use-urandom for luksFormat to allow + setting of RNG for volume key generator. + * Add crypt_set_rng_type() and crypt_get_rng_type() to API. + * Add crypt_set_uuid() to API. + * Allow UUID setting in luksFormat and luksUUID (--uuid parameter). + * Add --keyfile-size and --new-keyfile-size (in bytes) size and disallow overloading + of --key-size for limiting keyfile reads. + * Fix luksFormat to properly use key file with --master-key-file switch. + * Fix possible double free when handling master key file. + +2010-10-17 Milan Broz + * Add crypt_get_device_name() to API (get underlying device name). + * Change detection for static libraries. + * Fix pkg-config use in automake scripts. + * Remove --disable-shared-library switch and handle static library build + by common libtool logic (using --enable-static). + * Add --enable-static-cryptsetup option to build cryptsetup.static binary + together with shared build. + +2010-08-05 Milan Broz + * Wipe iteration and salt after KillSlot in LUKS header. + * Rewrite file differ test to C (and fix it to really work). + * Switch to 1MiB default alignment of data. + For more info see https://bugzilla.redhat.com/show_bug.cgi?id=621684 + * Do not query non-existent device twice (cryptsetup status /dev/nonexistent). + * Check if requested hash is supported before writing LUKS header. + +2010-07-28 Arno Wagner + * Add FAQ (Frequently Asked Questions) file to distribution. + +2010-07-03 Milan Broz + * Fix udev support for old libdevmapper with not compatible definition. + * Version 1.1.3. + +2010-06-01 Milan Broz + * Fix device alignment ioctl calls parameters. + * Fix activate_by_* API calls to handle NULL device name as documented. + +2010-05-30 Milan Broz + * Version 1.1.2. + +2010-05-27 Milan Broz + * Fix luksFormat/luksOpen reading passphrase from stdin and "-" keyfile. + * Support --key-file/-d option for luksFormat. + * Fix description of --key-file and add --verbose and --debug options to man page. + * Add verbose log level and move unlocking message there. + * Remove device even if underlying device disappeared. + * Fix (deprecated) reload device command to accept new device argument. + +2010-05-23 Milan Broz + * Fix luksClose operation for stacked DM devices. + * Version 1.1.1. + +2010-05-03 Milan Broz + * Fix automatic dm-crypt module loading. + * Escape hyphens in man page. + * Version 1.1.1-rc2. + +2010-04-30 Milan Broz + * Try to use pkgconfig for device mapper library. + * Detect old dm-crypt module and disable LUKS suspend/resume. + * Fix apitest to work on older systems. + * Allow no hash specification in plain device constructor. + * Fix luksOpen reading of passphrase on stdin (if "-" keyfile specified). + * Fix isLuks to initialise crypto backend (blkid instead is suggested anyway). + * Version 1.1.1-rc1. + +2010-04-12 Milan Broz + * Fix package config to use proper package version. + * Avoid class C++ keyword in library header. + * Detect and use devmapper udev support if available (disable by --disable-udev). + +2010-04-06 Milan Broz + * Prefer some device paths in status display. + * Support device topology detectionfor data alignment. + +2010-02-25 Milan Broz + * Do not verify unlocking passphrase in luksAddKey command. + * Properly initialise crypto backend in header backup/restore commands. + +2010-01-17 Milan Broz + * If gcrypt compiled with capabilities, document workaround for cryptsetup (see lib/gcrypt.c). + * Version 1.1.0. + +2010-01-10 Milan Broz + * Fix initialisation of gcrypt during luksFormat. + * Convert hash name to lower case in header (fix sha1 backward compatible header) + * Check for minimum required gcrypt version. + +2009-12-30 Milan Broz + * Fix key slot iteration count calculation (small -i value was the same as default). + * The slot and key digest iteration minimum is now 1000. + * The key digest iteration # is calculated from iteration time (approx 1/8 of that). + * Version 1.1.0-rc4. + +2009-12-11 Milan Broz + * Fix error handling during reading passhrase. + +2009-12-01 Milan Broz + * Allow changes of default compiled-in cipher parameters through configure. + * Switch default key size for LUKS to 256bits. + * Switch default plain mode to aes-cbc-essiv:sha256 (default is backward incompatible!). + +2009-11-14 Milan Broz + * Add CRYPT_ prefix to enum defined in libcryptsetup.h. + * Fix status call to fail when running as non-root user. + * Check in configure if selinux libraries are required in static version. + * Add temporary debug code to find processes locking internal device. + * Simplify build system, use autopoint and clean gettext processing. + * Use proper NLS macros and detection (so the message translation works again). + * Version 1.1.0-rc3. + +2009-09-30 Milan Broz + * Fix exported symbols and versions in libcryptsetup. + * Do not use internal lib functions in cryptsetup. + * Add crypt_log to library. + * Fix crypt_remove_device (remove, luksClose) implementation. + * Move dm backend initialisation to library calls. + * Move duplicate Command failed message to verbose level (error is printed always). + * Add some password and used algorithms notes to man page. + * Version 1.1.0-rc2. + +2009-09-28 Milan Broz + * Add luksHeaderBackup and luksHeaderRestore commands. + * Fail passphrase read if piped input no longer exists. + * Version 1.1.0-rc1. + +2009-09-15 Milan Broz + * Initialize crypto library before LUKS header load. + * Fix manpage to not require --size which expands to device size by default. + +2009-09-10 Milan Broz + * Clean up Makefiles and configure script. + * Version 1.1.0-test0. + +2009-09-08 Milan Broz + * Use dm-uuid for all crypt devices, contains device type and name now. + * Try to read first sector from device to properly check that device is ready. + +2009-09-02 Milan Broz + * Add luksSuspend (freeze device and wipe key) and luksResume (with provided passphrase). + +2009-08-30 Milan Broz + * Require device device-mapper to build and do not use backend wrapper for dm calls. + * Move memory locking and dm initialization to command layer. + * Increase priority of process if memory is locked. + * Add log macros and make logging more consistent. + * Move command successful messages to verbose level. + * Introduce --debug parameter. + * Move device utils code and provide context parameter (for log). + * Keyfile now must be provided by path, only stdin file descriptor is used (api only). + * Do not call isatty() on closed keyfile descriptor. + * Run performance check for PBKDF2 from LUKS code, do not mix hash algorithms results. + * Add ability to provide pre-generated master key and UUID in LUKS header format. + * Add LUKS function to verify master key digest. + * Move key slot manipulation function into LUKS specific code. + * Replace global options struct with separate parameters in helper functions. + * Add new libcryptsetup API (documented in libcryptsetup.h). + * Implement old API calls using new functions. + * Remove old API code helper functions. + * Add --master-key-file option for luksFormat and luksAddKey. + +2009-08-17 Milan Broz + * Fix PBKDF2 speed calculation for large passphrases. + * Allow using passphrase provided in options struct for LuksOpen. + * Allow restrict keys size in LuksOpen. + +2009-07-30 Milan Broz + * Fix errors when compiled with LUKS_DEBUG. + * Print error when getline fails. + * Remove po/cryptsetup-luks.pot, it's autogenerated. + * Return ENOENT for empty keyslots, EINVAL will be used later for other type of error. + * Switch PBKDF2 from internal SHA1 to libgcrypt, make hash algorithm not hardcoded to SHA1 here. + * Add required parameters for changing hash used in LUKS key setup scheme. + * Do not export simple XOR helper now used only inside AF functions. + * Completely remove internal SHA1 implementation code, not needed anymore. + * Enable hash algorithm selection for LUKS through -h luksFormat option. + +2009-07-28 Milan Broz + * Pad luks header to 512 sector size. + * Rework read/write blockwise to not split operation to many pieces. + * Use posix_memalign if available. + +2009-07-22 Milan Broz + * Fix segfault if provided slot in luksKillslot is invalid. + * Remove unneeded timeout when remove of temporary device succeeded. + +2009-07-22 Milan Broz + * version 1.0.7 + +2009-07-16 Milan Broz + * Allow removal of last slot in luksRemoveKey and luksKillSlot. + +2009-07-11 Milan Broz + + * Add --disable-selinux option and fix static build if selinux is required. + * Reject unsupported --offset and --skip options for luksFormat and update man page. + +2009-06-22 Milan Broz + + * Summary of changes in subversion for 1.0.7-rc1: + * Various man page fixes. + * Set UUID in device-mapper for LUKS devices. + * Retain readahead of underlying device. + * Display device name when asking for password. + * Check device size when loading LUKS header. Remove misleading error message later. + * Add error hint if dm-crypt mapping failed. + * Use better error messages if device doesn't exist or is already used by other mapping. + * Fix make distcheck. + * Check if all slots are full during luksAddKey. + * Fix segfault in set_error. + * Code cleanups, remove precompiled pot files, remove unnecessary files from po directory + * Fix uninitialized return value variable in setup.c. + * Code cleanups. (thanks to Ivan Stankovic) + * Fix wrong output for remaining key at key deletion. + * Allow deletion of key slot while other keys have the same key information. + * Add missing AM_PROG_CC_C_O to configure.in + * Remove duplicate sentence in man page. + * Wipe start of device (possible fs signature) before LUKS-formatting. + * Do not process configure.in in hidden directories. + * Return more descriptive error in case of IO or header format error. + * Use remapping to error target instead of calling udevsettle for temporary crypt device. + * Check device mapper communication and warn user if device-mapper support missing in kernel. + * Fix signal handler to properly close device. + * write_lseek_blockwise: declare innerCount outside the if block. + * add -Wall to the default CFLAGS. fix some signedness issues. + * Error handling improvement. + * Add non-exclusive override to interface definition. + * Refactor key slot selection into keyslot_from_option. + +2007-05-01 Clemens Fruhwirth + + * lib/backends.c, man/cryptsetup.8: Apply patch from Ludwig Nussel + , for old SuSE compat hashing. + +2007-04-16 Clemens Fruhwirth + + * Summary of changes in subversion: + Fix segfault for key size > 32 bytes. + Kick ancient header version conversion. + Fix http://bugs.debian.org/403075 + No passwort retrying for I/O errors. + Fix hang on "-i 0". + Fix parenthesization error that prevented --tries from working + correctly. + +2006-11-28 gettextize + + * m4/gettext.m4: Upgrade to gettext-0.15. + * m4/glibc2.m4: New file, from gettext-0.15. + * m4/intmax.m4: New file, from gettext-0.15. + * m4/inttypes-h.m4: New file, from gettext-0.15. + * m4/inttypes-pri.m4: Upgrade to gettext-0.15. + * m4/lib-link.m4: Upgrade to gettext-0.15. + * m4/lib-prefix.m4: Upgrade to gettext-0.15. + * m4/lock.m4: New file, from gettext-0.15. + * m4/longdouble.m4: New file, from gettext-0.15. + * m4/longlong.m4: New file, from gettext-0.15. + * m4/nls.m4: Upgrade to gettext-0.15. + * m4/po.m4: Upgrade to gettext-0.15. + * m4/printf-posix.m4: New file, from gettext-0.15. + * m4/signed.m4: New file, from gettext-0.15. + * m4/size_max.m4: New file, from gettext-0.15. + * m4/visibility.m4: New file, from gettext-0.15. + * m4/wchar_t.m4: New file, from gettext-0.15. + * m4/wint_t.m4: New file, from gettext-0.15. + * m4/xsize.m4: New file, from gettext-0.15. + * m4/Makefile.am: New file. + * configure.in (AC_OUTPUT): Add m4/Makefile. + (AM_GNU_GETTEXT_VERSION): Bump to 0.15. + +2006-10-22 David Härdeman + + * Allow hashing of keys passed through stdin. + +2006-10-13 Clemens Fruhwirth + + * configure.in: 1.0.4 release + +2006-10-13 Clemens Fruhwirth + + * man/cryptsetup.8: Document --tries switch; patch by Jonas + Meurer. + +2006-10-13 Clemens Fruhwirth + + * lib/setup.c: Added terminal timeout rewrite as forwarded by + Jonas Meurer + +2006-10-04 Clemens Fruhwirth + + * Merged patch from Marc Merlin to allow user + selection of key slot. + +2006-09-26 gettextize + + * m4/codeset.m4: Upgrade to gettext-0.14.4. + * m4/gettext.m4: Upgrade to gettext-0.14.4. + * m4/glibc2.m4: New file, from gettext-0.14.4. + * m4/glibc21.m4: Upgrade to gettext-0.14.4. + * m4/iconv.m4: Upgrade to gettext-0.14.4. + * m4/intdiv0.m4: Upgrade to gettext-0.14.4. + * m4/intmax.m4: New file, from gettext-0.14.4. + * m4/inttypes.m4: Upgrade to gettext-0.14.4. + * m4/inttypes_h.m4: Upgrade to gettext-0.14.4. + * m4/inttypes-pri.m4: Upgrade to gettext-0.14.4. + * m4/isc-posix.m4: Upgrade to gettext-0.14.4. + * m4/lcmessage.m4: Upgrade to gettext-0.14.4. + * m4/lib-ld.m4: Upgrade to gettext-0.14.4. + * m4/lib-link.m4: Upgrade to gettext-0.14.4. + * m4/lib-prefix.m4: Upgrade to gettext-0.14.4. + * m4/longdouble.m4: New file, from gettext-0.14.4. + * m4/longlong.m4: New file, from gettext-0.14.4. + * m4/nls.m4: Upgrade to gettext-0.14.4. + * m4/po.m4: Upgrade to gettext-0.14.4. + * m4/printf-posix.m4: New file, from gettext-0.14.4. + * m4/progtest.m4: Upgrade to gettext-0.14.4. + * m4/signed.m4: New file, from gettext-0.14.4. + * m4/size_max.m4: New file, from gettext-0.14.4. + * m4/stdint_h.m4: Upgrade to gettext-0.14.4. + * m4/uintmax_t.m4: Upgrade to gettext-0.14.4. + * m4/ulonglong.m4: Upgrade to gettext-0.14.4. + * m4/wchar_t.m4: New file, from gettext-0.14.4. + * m4/wint_t.m4: New file, from gettext-0.14.4. + * m4/xsize.m4: New file, from gettext-0.14.4. + * Makefile.am (ACLOCAL_AMFLAGS): New variable. + * configure.in (AM_GNU_GETTEXT_VERSION): Bump to 0.14.4. + +2006-08-04 Clemens Fruhwirth + + * configure.in: 1.0.4-rc2 + +2006-08-04 Clemens Fruhwirth + + * luks/Makefile.am: Add a few regression tests + +2006-08-04 Clemens Fruhwirth + + * lib/setup.c (get_key): Applied patch from David Härdeman + for reading binary keys from stdin using + the "-" as key file. + +2006-08-04 Clemens Fruhwirth + + * lib/setup.c (__crypt_luks_add_key): For checking options struct + (optionsCheck) filter out CRYPT_FLAG_VERIFY and + CRYPT_FLAG_VERIFY_IF_POSSIBLE, so that in no case password verification is done + for password retrieval. + +2006-08-04 Clemens Fruhwirth + + * configure.in: Merge Patch from http://bugs.gentoo.org/show_bug.cgi?id=132126 for sepol + +2006-07-23 Clemens Fruhwirth + + * Applied patches from David Härdeman to fix 64 + bit compiler warning issues. + +2006-05-19 Clemens Fruhwirth + + * Applied patches from Jonas Meurer + - fix terminal status after timeout + - add remark for --tries to manpage + - allow more than 32 chars from standard input. + - exit status fix for cryptsetup status. + +2006-05-06 Clemens Fruhwirth + + * src/cryptsetup.c (yesDialog): Fix getline problem for 64-bit archs. + +2006-04-05 Clemens Fruhwirth + + * configure.in: Release 1.0.3. + + * Applied patch by Johannes Weißl for more meaningful exit codes + and password retries + +2006-03-30 Clemens Fruhwirth + + * lib/setup.c (__crypt_create_device): (char *) -> (const char *) + +2006-03-30 Clemens Fruhwirth + + * Apply alignPayload patch from Peter Palfrader + +2006-03-15 Clemens Fruhwirth + + * configure.in: 1.0.3-rc3. Most displease release ever. + * lib/setup.c (__crypt_create_device): More verbose error message. + +2006-02-26 Clemens Fruhwirth + + * lib/setup.c: Revert to 1.0.1 key reading. + +2006-02-25 Clemens Fruhwirth + + * man/cryptsetup.8: merge patch from Jonas Meurer + +2006-02-25 Clemens Fruhwirth + + * configure.in: 1.0.3-rc2 + +2006-02-25 Clemens Fruhwirth + + * lib/libdevmapper.c (dm_create_device): Remove dup check here. + * lib/setup.c (__crypt_luks_open): Adopt same dup check as regular + create command. + +2006-02-22 Clemens Fruhwirth + + * configure.in: Spin 1.0.3-rc1 + +2006-02-22 Clemens Fruhwirth + + * src/cryptsetup.c (action_create): Change defaulting. + (action_luksFormat): Change defaulting. + + * lib/setup.c (parse_into_name_and_mode): Revert that default + change. This is FORBIDDEN here, as it will change cryptsetup + entire default. This is BAD in a non-LUKS world. + +2006-02-21 Clemens Fruhwirth + + * luks/keyencryption.c (setup_mapping): Add proper size restriction to mapping. + (LUKS_endec_template): Add more verbose error message. + +2006-02-21 Clemens Fruhwirth + + * lib/libdevmapper.c (dm_query_device): Incorporate patch from + Bastian Blank + http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=344313 + +2006-02-21 Clemens Fruhwirth + + * src/cryptsetup.c: Rename show_error -> show_status. + +2006-02-20 Clemens Fruhwirth + + * lib/libdevmapper.c (dm_create_device): Prevent existing mapping + from being removed when a mapping with the same name is added + + * Add timeout patch from Jonas Meurer + + * src/cryptsetup.c: Remove conditional error printing to enable + printing the no-error msg (Command successful). Verify passphrase + for LUKS volumes. + (main): Add no-verify-passphrase + + * lib/setup.c (parse_into_name_and_mode): Change default mode complition to essiv:sha256. + +2006-01-04 Clemens Fruhwirth + + * src/cryptsetup.c (help): Merge patch from Gentoo: change gettext(..) to _(..). + +2005-12-06 Clemens Fruhwirth + + * man/cryptsetup.8: Correct "seconds" to "microseconds" in the explanation for -i. + +2005-11-09 Clemens Fruhwirth + + * src/cryptsetup.c (main): Add version string. + +2005-11-08 Clemens Fruhwirth + + * lib/backends.c: compile fix. + +2005-09-11 Clemens Fruhwirth + + * lib/setup.c (get_key): Fixed another incompatibility from my + get_key rewrite with original cryptsetup. + +2005-09-11 Clemens Fruhwirth + + * Merged changes from Florian Knauf's fk02 branch. + +2005-09-08 Clemens Fruhwirth + + * lib/setup.c (get_key): Fixed another incompatibility with + original cryptsetup. + +2005-08-20 Clemens Fruhwirth + + * Checked in a patch from Michael Gebetsroither + to silent all confirmation dialogs. + +2005-06-23 Clemens Fruhwirth + + * src/cryptsetup.c (help): print PACKAGE_STRING + +2005-06-20 Clemens Fruhwirth + + * luks/keymanage.c (LUKS_set_key): Security check against header manipulation + + * src/cryptsetup.c (action_luksDelKey): Safety check in luksDelKey + + * luks/keymanage.c: Changed disk layout generation to align key material to 4k boundaries. + (LUKS_is_last_keyslot): Added LUKS_is_last_keyslot function. + + * Applied patch from Bill Nottingham fixing a lot of prototypes. + + * src/cryptsetup.c (action_luksOpen): Add support for -r flag. + + * configure.in: Version bump 1.0.1 + +2005-06-16 Clemens Fruhwirth + + * lib/setup.c (__crypt_luks_open): Remove mem leaking of dmCipherSpec. + (get_key): Fix missing zero termination for read string. + +2005-06-12 Clemens Fruhwirth + + * luks/keyencryption.c (setup_mapping): Added CRYPT_FLAG_READONLY in case of O_RDONLY mode + +2005-06-11 Clemens Fruhwirth + + * configure.in: Version bump 1.0.1-pre + +2005-06-09 Clemens Fruhwirth + + * lib/utils.c: Added write_llseek_blocksize method to support sector wiping on sector_size != 512 + media + +2005-05-23 Clemens Fruhwirth + + * lib/setup.c (crypt_luksDelKey): Added missing return statement + (setup_leave): Added missing return statement + + * luks/keyencryption.c (clear_mapping): Added missing return statement + +2005-05-19 Clemens Fruhwirth + + * lib/utils.c (write_blockwise, read_blockwise): Changed to soft bsize instead of SECTOR_SIZE + + * luks/keymanage.c (wipe): Changed open mode to O_DIRECT | O_SYNC, and changed write + to use the blockwise write helper + +2005-04-21 Clemens Fruhwirth + + * man/cryptsetup.8: Corrected an error, thanks to Dick Middleton. + +2005-04-09 Clemens Fruhwirth + + * luks/sha/hmac.c: Add 64 bit bug fix courtesy to + Oliver Paukstadt . + + * luks/pbkdf.c, luks/keyencryption.c, luks/keymanage.c, luks/af.c: Added a license + disclaimer and remove option for "any future GPL versions". + +2005-03-25 Clemens Fruhwirth + + * configure.in: man page Makefile. Version bump 1.0. + + * man/cryptsetup.8: finalize man page and move to section 8. + + * src/cryptsetup.c (action_luksFormat): Add "are you sure" for interactive sessions. + + * lib/setup.c (crypt_luksDump), src/cryptsetup.c: add LUKS dump command + +2005-03-24 Clemens Fruhwirth + + * src/cryptsetup.c, luks/Makefile.am (test), lib/setup.c (setup_enter): + rename luksInit to luksFormat + +2005-03-12 Clemens Fruhwirth + + * man/cryptsetup.1: Add man page. + + * lib/setup.c: Remove unnecessary LUKS_write_phdr call, so the + phdr is written after passphrase reading, so the user can change + his mind, and not have a partial written LUKS header on it's disk. + +2005-02-09 Clemens Fruhwirth + + * luks/keymanage.c (LUKS_write_phdr): converted argument phdr to + pointer, and make a copy of phdr for conversion + + * configure.in: Version dump. + + * luks/keyencryption.c: Convert to read|write_blockwise. + + * luks/keymanage.c: Convert to read|write_blockwise. + + * lib/utils.c: Add read|write_blockwise functions, to use in + O_DIRECT file accesses. + +2004-03-11 Thursday 15:52 Jana Saout + + * lib/blockdev.h: BLKGETSIZE64 really uses size_t as third + argument, the rest is wrong. + +2004-03-10 Wednesday 17:50 Jana Saout + + * lib/: libcryptsetup.h, libdevmapper.c: Small fixes. + +2004-03-09 Tuesday 21:41 Jana Saout + + * lib/internal.h, lib/libcryptsetup.h, lib/libdevmapper.c, + lib/setup.c, po/de.po, src/cryptsetup.c: Added internal flags to + keep track of malloc'ed return values in struct crypt_options and + add a function to free the memory. Also add a readonly flag to + libcryptsetup. + +2004-03-09 Tuesday 16:03 Jana Saout + + * ChangeLog, configure.in, setup-gettext, lib/Makefile.am, + lib/backends.c, lib/blockdev.h, lib/gcrypt.c, lib/internal.h, + lib/libcryptsetup.h, lib/libdevmapper.c, lib/setup.c, + lib/utils.c, po/de.po, src/Makefile.am, src/cryptsetup.c: More + reorganization work. + +2004-03-08 Monday 01:38 Jana Saout + + * ChangeLog, Makefile.am, acinclude.m4, configure.in, + lib/Makefile.am, lib/backends.c, lib/blockdev.h, lib/gcrypt.c, + lib/libdevmapper.c, lib/setup.c, lib/utils.c, po/de.po, + src/Makefile.am: BLKGETSIZE64 fixes and started modularity + enhancements + +2004-03-04 Thursday 21:06 Jana Saout + + * Makefile.am, po/de.po, src/cryptsetup.c, src/cryptsetup.h: First + backward compatible working version. + +2004-03-04 Thursday 00:42 Jana Saout + + * NEWS, AUTHORS, ChangeLog, Makefile.am, README, autogen.sh, + configure.in, setup-gettext, po/ChangeLog, po/LINGUAS, + po/POTFILES.in, po/de.po, src/cryptsetup.c, src/cryptsetup.h, + src/Makefile.am (utags: initial): Initial checkin. + +2004-03-04 Thursday 00:42 Jana Saout + + * NEWS, AUTHORS, ChangeLog, Makefile.am, README, autogen.sh, + configure.in, setup-gettext, po/ChangeLog, po/LINGUAS, + po/POTFILES.in, po/de.po, src/cryptsetup.c, src/cryptsetup.h, + src/Makefile.am: Initial revision diff --git a/docs/Keyring.txt b/docs/Keyring.txt new file mode 100644 index 0000000..bdcc838 --- /dev/null +++ b/docs/Keyring.txt @@ -0,0 +1,56 @@ +Integration with kernel keyring service +--------------------------------------- + +We have two different use cases for kernel keyring service: + +I) Volume keys + +Since upstream kernel 4.10 dm-crypt device mapper target allows loading volume +key (VK) in kernel keyring service. The key offloaded in kernel keyring service +is only referenced (by key description) in dm-crypt target and the VK is therefore +no longer stored directly in dm-crypt target. Starting with cryptsetup 2.0 we +load VK in kernel keyring by default for LUKSv2 devices (when dm-crypt with the +feature is available). + +Currently cryptsetup loads VK in 'logon' type kernel key so that VK is passed in +the kernel and can't be read from userspace afterward. Also cryptsetup loads VK in +thread keyring (before passing the reference to dm-crypt target) so that the key +lifetime is directly bound to the process that performs the dm-crypt setup. When +cryptsetup process exits (for whatever reason) the key gets unlinked in kernel +automatically. In summary, the key description visible in dm-crypt table line is +a reference to VK that usually no longer exists in kernel keyring service if you +used cryptsetup to for device activation. + +Using this feature dm-crypt no longer maintains a direct key copy (but there's +always at least one copy in kernel crypto layer). + +II) Keyslot passphrase +The second use case for kernel keyring is to allow cryptsetup reading the keyslot +passphrase stored in kernel keyring instead. The user may load passphrase in kernel +keyring and notify cryptsetup to read it from there later. Currently, cryptsetup +cli supports kernel keyring for passphrase only via LUKS2 internal token +(luks2-keyring). Library also provides a general method for device activation by +reading passphrase from keyring: crypt_activate_by_keyring(). The key type +for use case II) must always be 'user' since we need to read the actual key +data from userspace unlike with VK in I). Ability to read keyslot passphrase +from kernel keyring also allows easily auto-activate LUKS2 devices. + +Simple example how to use kernel keyring for keyslot passphrase: + +1) create LUKS2 keyring token for keyslot 0 (in LUKS2 device/image) +cryptsetup token add --key-description my:key -S 0 /dev/device + +2) Load keyslot passphrase in user keyring +read -s -p "Keyslot passphrase: "; echo -n $REPLY | keyctl padd user my:key @u + +3) Activate device using passphrase stored in kernel keyring +cryptsetup open /dev/device my_unlocked_device + +4a) unlink the key when no longer needed by +keyctl unlink %user:my:key @u + +4b) or revoke it immediately by +keyctl revoke %user:my:key + +If cryptsetup asks for passphrase in step 3) something went wrong with keyring +activation. See --debug output then. diff --git a/docs/LUKS2-locking.txt b/docs/LUKS2-locking.txt new file mode 100644 index 0000000..e401b61 --- /dev/null +++ b/docs/LUKS2-locking.txt @@ -0,0 +1,61 @@ +LUKS2 device locking overview +============================= + +Why +~~~ + +LUKS2 format keeps two identical copies of metadata stored consecutively +at the head of metadata device (file or bdev). The metadata +area (both copies) must be updated in a single atomic operation to avoid +header corruption during concurrent write. + +While with LUKS1 users may have clear knowledge of when a LUKS header is +being updated (written to) or when it's being read solely the need for +locking with legacy format was not so obvious as it is with the LUKSv2 format. + +With LUKS2 the boundary between read-only and read-write is blurry and what +used to be the exclusively read-only operation (i.e., cryptsetup open command) may +easily become read-update operation silently without user's knowledge. +Major feature of LUKS2 format is resilience against accidental +corruption of metadata (i.e., partial header overwrite by parted or cfdisk +while creating partition on mistaken block device). +Such header corruption is detected early on header read and auto-recovery +procedure takes place (the corrupted header with checksum mismatch is being +replaced by the secondary one if that one is intact). +On current Linux systems header load operation may be triggered without user +direct intervention for example by udev rule or from systemd service. +Such clash of header read and auto-recovery procedure could have severe +consequences with the worst case of having LUKS2 device unaccessible or being +broken beyond repair. + +The whole locking of LUKSv2 device headers split into two categories depending +what backend the header is stored on: + +I) block device +~~~~~~~~~~~~~~~ + +We perform flock() on file descriptors of files stored in a private +directory (by default /run/lock/cryptsetup). The file name is derived +from major:minor couple of affected block device. Note we recommend +that access to private locking directory is supposed to be limited +to superuser only. For this method to work the distribution needs +to install the locking directory with appropriate access rights. + +II) regular files +~~~~~~~~~~~~~~~~~ + +First notable difference between headers stored in a file +vs. headers stored in a block device is that headers in a file may be +manipulated by the regular user unlike headers on block devices. Therefore +we perform flock() protection on file with the luks2 header directly. + +Limitations +~~~~~~~~~~~ + +a) In general, the locking model provides serialization of I/Os targeting +the header only. It means the header is always written or read at once +while locking is enabled. +We do not suppress any other negative effect that two or more concurrent +writers of the same header may cause. + +b) The locking is not cluster aware in any way. diff --git a/docs/doxyfile b/docs/doxyfile new file mode 100644 index 0000000..0943772 --- /dev/null +++ b/docs/doxyfile @@ -0,0 +1,335 @@ +# Doxyfile 1.9.1 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "cryptsetup API" +PROJECT_NUMBER = +PROJECT_BRIEF = "Public cryptsetup API" +PROJECT_LOGO = +OUTPUT_DIRECTORY = doxygen_api_docs +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +OUTPUT_TEXT_DIRECTION = None +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = YES +LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +RESOLVE_UNNAMED_PARAMS = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = doxygen_index.h \ + ../lib/libcryptsetup.h +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = examples +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_ADD_INC_PATHS = YES +CLANG_OPTIONS = +CLANG_DATABASE_PATH = +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = YES +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = YES +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +HTML_FORMULA_FORMAT = png +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +FORMULA_MACROFILE = +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = http://www.mathjax.org/mathjax +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +LATEX_MAKEINDEX_CMD = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain +LATEX_TIMESTAMP = NO +LATEX_EMOJI_DIRECTORY = +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +RTF_SOURCE_CODE = NO +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_SUBDIR = +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +XML_NS_MEMB_FILE_SCOPE = NO +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = YES +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/docs/doxygen_index.h b/docs/doxygen_index.h new file mode 100644 index 0000000..8bdf05f --- /dev/null +++ b/docs/doxygen_index.h @@ -0,0 +1,110 @@ +/*! \mainpage Cryptsetup API + * + * The documentation covers public parts of cryptsetup API. In the following sections you'll find + * the examples that describe some features of cryptsetup API. + * For more info about libcryptsetup API versions see + * API Tracker. + * + *
    + *
  1. @ref cexamples "Cryptsetup API examples"
    2. + *
      + *
    1. @ref cluks "crypt_luks_usage" - cryptsetup LUKS device type usage examples
      2. + *
        + *
      • @ref cinit "crypt_init()"
        • + *
      • @ref cformat "crypt_format()" - header and payload on mutual device
        • + *
      • @ref ckeys "Keyslot operations"
        • + *
          + *
        • @ref ckeyslot_vol "crypt_keyslot_add_by_volume_key()"
          • + *
        • @ref ckeyslot_pass "crypt_keyslot_add_by_passphrase()"
          • + *
        + *
      • @ref cload "crypt_load()" + *
      • @ref cactivate "crypt_activate_by_passphrase()"
        • + *
      • @ref cactive_pars "crypt_get_active_device()"
        • + *
      • @ref cinit_by_name "crypt_init_by_name()"
        • + *
      • @ref cdeactivate "crypt_deactivate()"
        • + *
      • @ref cluks_ex "crypt_luks_usage.c"
        • + *
      + *
    2. @ref clog "crypt_log_usage" - cryptsetup logging API examples
      3. + *
    + *
+ * + * @section cexamples Cryptsetup API examples + * @section cluks crypt_luks_usage - cryptsetup LUKS device type usage + * @subsection cinit crypt_init() + * Every time you need to do something with cryptsetup or dmcrypt device + * you need a valid context. The first step to start your work is + * @ref crypt_init call. You can call it either with path + * to the block device or path to the regular file. If you don't supply the path, + * empty context is initialized. + * + * @subsection cformat crypt_format() - header and payload on mutual device + * This section covers basic use cases for formatting LUKS devices. Format operation + * sets device type in context and in case of LUKS header is written at the beginning + * of block device. In the example below we use the scenario where LUKS header and data + * are both stored on the same device. There's also a possibility to store header and + * data separately. + * + * Bear in mind that @ref crypt_format() is destructive operation and it + * overwrites part of the backing block device. + * + * @subsection ckeys Keyslot operations examples + * After successful @ref crypt_format of LUKS device, volume key is not stored + * in a persistent way on the device. Keyslot area is an array beyond LUKS header, where + * volume key is stored in the encrypted form using user input passphrase. For more info about + * LUKS keyslots and how it's actually protected, please look at + * LUKS specification. + * There are two basic methods to create a new keyslot: + * + * @subsection ckeyslot_vol crypt_keyslot_add_by_volume_key() + * Creates a new keyslot directly by encrypting volume_key stored in the device + * context. Passphrase should be supplied or user is prompted if passphrase param is + * NULL. + * + * @subsection ckeyslot_pass crypt_keyslot_add_by_passphrase() + * Creates a new keyslot for the volume key by opening existing active keyslot, + * extracting volume key from it and storing it into a new keyslot + * protected by a new passphrase + * + * @subsection cload crypt_load() + * Function loads header from backing block device into device context. + * + * @subsection cactivate crypt_activate_by_passphrase() + * Activates crypt device by user supplied password for keyslot containing the volume_key. + * If keyslot parameter is set to CRYPT_ANY_SLOT then all active keyslots + * are tried one by one until the volume key is found. + * + * @subsection cactive_pars crypt_get_active_device() + * This call returns structure containing runtime attributes of active device. + * + * @subsection cinit_by_name crypt_init_by_name() + * In case you need to do operations with active device (device which already + * has its corresponding mapping) and you miss valid device context stored in + * *crypt_device reference, you should use this call. Function tries to + * get path to backing device from DM, initializes context for it and loads LUKS + * header. + * + * @subsection cdeactivate crypt_deactivate() + * Deactivates crypt device (removes DM mapping and safely erases volume key from kernel). + * + * @subsection cluks_ex crypt_luks_usage.c - Complex example + * To compile and run use following commands in examples directory: + * + * @code + * make + * ./crypt_luks_usage _path_to_[block_device]_file + * @endcode + * Note that you need to have the cryptsetup library compiled. @include crypt_luks_usage.c + * + * @section clog crypt_log_usage - cryptsetup logging API example + * Example describes basic use case for cryptsetup logging. To compile and run + * use following commands in examples directory: + * + * @code + * make + * ./crypt_log_usage + * @endcode + * Note that you need to have the cryptsetup library compiled. @include crypt_log_usage.c + * + * @example crypt_luks_usage.c + * @example crypt_log_usage.c + */ diff --git a/docs/examples/Makefile b/docs/examples/Makefile new file mode 100644 index 0000000..845b6cb --- /dev/null +++ b/docs/examples/Makefile @@ -0,0 +1,17 @@ +TARGETS=crypt_log_usage crypt_luks_usage +CFLAGS=-O0 -g -Wall -D_GNU_SOURCE +LDLIBS=-lcryptsetup +CC=gcc + +all: $(TARGETS) + +crypt_log_usage: crypt_log_usage.o + $(CC) -o $@ $^ $(LDLIBS) + +crypt_luks_usage: crypt_luks_usage.o + $(CC) -o $@ $^ $(LDLIBS) + +clean: + rm -f *.o *~ core $(TARGETS) + +.PHONY: clean diff --git a/docs/examples/crypt_log_usage.c b/docs/examples/crypt_log_usage.c new file mode 100644 index 0000000..3d08c34 --- /dev/null +++ b/docs/examples/crypt_log_usage.c @@ -0,0 +1,94 @@ +/* + * libcryptsetup API log example + * + * Copyright (C) 2011-2023 Red Hat, Inc. All rights reserved. + * + * This file is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This file is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this file; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + */ + +#include +#include +#include +#include +#include + +/* + * This is an example of crypt_set_log_callback API callback. + * + */ +static void simple_syslog_wrapper(int level, const char *msg, void *usrptr) +{ + const char *prefix = (const char *)usrptr; + int priority; + + switch(level) { + case CRYPT_LOG_NORMAL: priority = LOG_NOTICE; break; + case CRYPT_LOG_ERROR: priority = LOG_ERR; break; + case CRYPT_LOG_VERBOSE: priority = LOG_INFO; break; + case CRYPT_LOG_DEBUG: priority = LOG_DEBUG; break; + default: + fprintf(stderr, "Unsupported log level requested!\n"); + return; + } + + if (prefix) + syslog(priority, "%s:%s", prefix, msg); + else + syslog(priority, "%s", msg); +} + +int main(void) +{ + struct crypt_device *cd; + char usrprefix[] = "cslog_example"; + int r; + + if (geteuid()) { + printf("Using of libcryptsetup requires super user privileges.\n"); + return 1; + } + + openlog("cryptsetup", LOG_CONS | LOG_PID, LOG_USER); + + /* Initialize empty crypt device context */ + r = crypt_init(&cd, NULL); + if (r < 0) { + printf("crypt_init() failed.\n"); + return 2; + } + + /* crypt_set_log_callback() - register a log callback for crypt context */ + crypt_set_log_callback(cd, &simple_syslog_wrapper, (void *)usrprefix); + + /* send messages ithrough the crypt_log() interface */ + crypt_log(cd, CRYPT_LOG_NORMAL, "This is normal log message"); + crypt_log(cd, CRYPT_LOG_ERROR, "This is error log message"); + crypt_log(cd, CRYPT_LOG_VERBOSE, "This is verbose log message"); + crypt_log(cd, CRYPT_LOG_DEBUG, "This is debug message"); + + /* release crypt context */ + crypt_free(cd); + + /* Initialize default (global) log callback */ + crypt_set_log_callback(NULL, &simple_syslog_wrapper, NULL); + + crypt_log(NULL, CRYPT_LOG_NORMAL, "This is normal log message"); + crypt_log(NULL, CRYPT_LOG_ERROR, "This is error log message"); + crypt_log(NULL, CRYPT_LOG_VERBOSE, "This is verbose log message"); + crypt_log(NULL, CRYPT_LOG_DEBUG, "This is debug message"); + + closelog(); + return 0; +} diff --git a/docs/examples/crypt_luks_usage.c b/docs/examples/crypt_luks_usage.c new file mode 100644 index 0000000..d7779bd --- /dev/null +++ b/docs/examples/crypt_luks_usage.c @@ -0,0 +1,250 @@ +/* + * libcryptsetup API - using LUKS device example + * + * Copyright (C) 2011-2023 Red Hat, Inc. All rights reserved. + * + * This file is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This file is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this file; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + */ + +#include +#include +#include +#include +#include +#include +#include + +static int format_and_add_keyslots(const char *path) +{ + struct crypt_device *cd; + int r; + + /* + * The crypt_init() call is used to initialize crypt_device context, + * The path parameter specifies a device path. + * + * For path, you can use either link to a file or block device. + * The loopback device will be detached automatically. + */ + + r = crypt_init(&cd, path); + if (r < 0) { + printf("crypt_init() failed for %s.\n", path); + return r; + } + + printf("Context is attached to block device %s.\n", crypt_get_device_name(cd)); + + /* + * So far, no data were written to the device. + */ + printf("Device %s will be formatted as a LUKS device after 5 seconds.\n" + "Press CTRL+C now if you want to cancel this operation.\n", path); + sleep(5); + + /* + * NULLs for uuid and volume_key means that these attributes will be + * generated during crypt_format(). + */ + r = crypt_format(cd, /* crypt context */ + CRYPT_LUKS2, /* LUKS2 is a new LUKS format; use CRYPT_LUKS1 for LUKS1 */ + "aes", /* used cipher */ + "xts-plain64", /* used block mode and IV */ + NULL, /* generate UUID */ + NULL, /* generate volume key from RNG */ + 512 / 8, /* 512bit key - here AES-256 in XTS mode, size is in bytes */ + NULL); /* default parameters */ + + if (r < 0) { + printf("crypt_format() failed on device %s\n", crypt_get_device_name(cd)); + crypt_free(cd); + return r; + } + + /* + * The device now contains a LUKS header, but there is no active keyslot. + * + * crypt_keyslot_add_* call stores the volume_key in the encrypted form into the keyslot. + * + * After format, the volume key is stored internally. + */ + r = crypt_keyslot_add_by_volume_key(cd, /* crypt context */ + CRYPT_ANY_SLOT, /* just use first free slot */ + NULL, /* use internal volume key */ + 0, /* unused (size of volume key) */ + "foo", /* passphrase - NULL means query*/ + 3); /* size of passphrase */ + + if (r < 0) { + printf("Adding keyslot failed.\n"); + crypt_free(cd); + return r; + } + + printf("The first keyslot is initialized.\n"); + + /* + * Add another keyslot, now authenticating with the first keyslot. + * It decrypts the volume key from the first keyslot and creates a new one with the specified passphrase. + */ + r = crypt_keyslot_add_by_passphrase(cd, /* crypt context */ + CRYPT_ANY_SLOT, /* just use first free slot */ + "foo", 3, /* passphrase for the old keyslot */ + "bar", 3); /* passphrase for the new kesylot */ + if (r < 0) { + printf("Adding keyslot failed.\n"); + crypt_free(cd); + return r; + } + + printf("The second keyslot is initialized.\n"); + + crypt_free(cd); + return 0; +} + +static int activate_and_check_status(const char *path, const char *device_name) +{ + struct crypt_device *cd; + struct crypt_active_device cad; + int r; + + /* + * LUKS device activation example. + */ + r = crypt_init(&cd, path); + if (r < 0) { + printf("crypt_init() failed for %s.\n", path); + return r; + } + + /* + * crypt_load() is used to load existing LUKS header from a block device + */ + r = crypt_load(cd, /* crypt context */ + CRYPT_LUKS, /* requested type - here LUKS of any type */ + NULL); /* additional parameters (not used) */ + + if (r < 0) { + printf("crypt_load() failed on device %s.\n", crypt_get_device_name(cd)); + crypt_free(cd); + return r; + } + + /* + * Device activation creates a device-mapper device with the specified name. + */ + r = crypt_activate_by_passphrase(cd, /* crypt context */ + device_name, /* device name to activate */ + CRYPT_ANY_SLOT,/* the keyslot use (try all here) */ + "foo", 3, /* passphrase */ + CRYPT_ACTIVATE_READONLY); /* flags */ + if (r < 0) { + printf("Device %s activation failed.\n", device_name); + crypt_free(cd); + return r; + } + + printf("%s device %s/%s is active.\n", crypt_get_type(cd), crypt_get_dir(), device_name); + printf("\tcipher used: %s\n", crypt_get_cipher(cd)); + printf("\tcipher mode: %s\n", crypt_get_cipher_mode(cd)); + printf("\tdevice UUID: %s\n", crypt_get_uuid(cd)); + + /* + * Get info about the active device. + */ + r = crypt_get_active_device(cd, device_name, &cad); + if (r < 0) { + printf("Get info about active device %s failed.\n", device_name); + crypt_deactivate(cd, device_name); + crypt_free(cd); + return r; + } + + printf("Active device parameters for %s:\n" + "\tDevice offset (in sectors): %" PRIu64 "\n" + "\tIV offset (in sectors) : %" PRIu64 "\n" + "\tdevice size (in sectors) : %" PRIu64 "\n" + "\tread-only flag : %s\n", + device_name, cad.offset, cad.iv_offset, cad.size, + cad.flags & CRYPT_ACTIVATE_READONLY ? "1" : "0"); + + crypt_free(cd); + return 0; +} + +static int handle_active_device(const char *device_name) +{ + struct crypt_device *cd; + int r; + + /* + * crypt_init_by_name() initializes context by an active device-mapper name + */ + r = crypt_init_by_name(&cd, device_name); + if (r < 0) { + printf("crypt_init_by_name() failed for %s.\n", device_name); + return r; + } + + if (crypt_status(cd, device_name) == CRYPT_ACTIVE) + printf("Device %s is still active.\n", device_name); + else { + printf("Something failed perhaps, device %s is not active.\n", device_name); + crypt_free(cd); + return -1; + } + + /* + * crypt_deactivate() is used to deactivate a device + */ + r = crypt_deactivate(cd, device_name); + if (r < 0) { + printf("crypt_deactivate() failed.\n"); + crypt_free(cd); + return r; + } + + printf("Device %s is now deactivated.\n", device_name); + + crypt_free(cd); + return 0; +} + +int main(int argc, char **argv) +{ + if (geteuid()) { + printf("Using of libcryptsetup requires super user privileges.\n"); + return 1; + } + + if (argc != 2) { + printf("usage: ./crypt_luks_usage \n" + " refers to either a regular file or a block device.\n" + " WARNING: the file or device will be wiped.\n"); + return 2; + } + + if (format_and_add_keyslots(argv[1])) + return 3; + + if (activate_and_check_status(argv[1], "example_device")) + return 4; + + if (handle_active_device("example_device")) + return 5; + + return 0; +} diff --git a/docs/on-disk-format-luks2.pdf b/docs/on-disk-format-luks2.pdf new file mode 100644 index 0000000..d89bcef Binary files /dev/null and b/docs/on-disk-format-luks2.pdf differ diff --git a/docs/on-disk-format.pdf b/docs/on-disk-format.pdf new file mode 100644 index 0000000..7f6e5e7 Binary files /dev/null and b/docs/on-disk-format.pdf differ diff --git a/docs/v1.0.7-ReleaseNotes b/docs/v1.0.7-ReleaseNotes new file mode 100644 index 0000000..9288c60 --- /dev/null +++ b/docs/v1.0.7-ReleaseNotes @@ -0,0 +1,92 @@ +cryptsetup 1.0.7 Release Notes (2009-07-22) +=========================================== + +Changes since 1.0.7-rc1 +------------------------ +[committer name] + + * Allow removal of last slot in luksRemoveKey +and luksKillSlot. [Milan Broz] + + * Add --disable-selinux option and fix static build if selinux +is required. [Milan Broz] + + * Reject unsupported --offset and --skip options for luksFormat +and update man page. [Milan Broz] + + +Changes since 1.0.6 +-------------------- +[committer name] + +* Various man page fixes. Also merged some Debian/Ubuntu man page +fixes. (thanks to Martin Pitt) [Milan Broz] + +* Set UUID in device-mapper for LUKS devices. [Milan Broz] + +* Retain readahead of underlying device. [Milan Broz] + +* Display device name when asking for password. (thanks to Till +Maas) [Milan Broz] + +* Check device size when loading LUKS header. Remove misleading +error message later. [Milan Broz] + +* Add error hint if dm-crypt mapping failed. (Key size and kernel +version check for XTS and LRW mode for now.) [Milan Broz] + +* Use better error messages if device doesn't exist or is already +used by other mapping. [Milan Broz] + +* Fix make distcheck. (thanks to Mike Kelly) [Milan Broz] + +* Check if all slots are full during luksAddKey. [Clemens Fruhwirth] + +* Fix segfault in set_error (thanks to Oliver Metz). [Clemens Fruhwirth] + +* Remove precompiled pot files. Fix uninitialized return value +variable in setup.c. [Clemens Fruhwirth] + +* Code cleanups. (thanks to Ivan Stankovic) [Clemens Fruhwirth] + +* Remove unnecessary files from po directory. They will be +regenerated by autogen.sh. [Clemens Fruhwirth] + +* Fix wrong output for remaining key at key deletion. Allow deletion +of key slot while other keys have the same key information. [Clemens +Fruhwirth] + +* Add missing AM_PROG_CC_C_O to configure.in [Milan Broz] + +* Remove duplicate sentence in man page (thanks to Till Maas). +[Milan Broz] + +* Wipe start of device (possible fs signature) before +LUKS-formatting. [Milan Broz] + +* Do not process configure.in in hidden directories. [Milan Broz] + +* Return more descriptive error in case of IO or header format +error. [Milan Broz] + +* Use remapping to error target instead of calling udevsettle +for temporary crypt device. [Milan Broz] + +* Check device mapper communication and warn user in case the +communication fails. (thanks to Milan Broz) [Clemens Fruhwirth] + +* Fix signal handler to proper close device. (thanks to Milan Broz) +[Clemens Fruhwirth] + +* write_lseek_blockwise: declare innerCount outside the if block, +add -Wall to the default CFLAGS, * fix some signedness issues +(thanks to Ivan Stankovic) [Clemens Fruhwirth] + +* Error handling improvement. (thanks to Erik Edin) [Clemens Fruhwirth] + +* Add non-exclusive override to interface definition. [Clemens +Fruhwirth] + +* Refactor key slot selection into keyslot_from_option. Either +autoselect next free keyslot or honor user choice (after checking). +[Clemens Fruhwirth] diff --git a/docs/v1.1.0-ReleaseNotes b/docs/v1.1.0-ReleaseNotes new file mode 100644 index 0000000..7ee6dea --- /dev/null +++ b/docs/v1.1.0-ReleaseNotes @@ -0,0 +1,110 @@ +Cryptsetup 1.1.0 Release Notes +============================== + +Changes since version 1.0.7 +---------------------------- + +Important changes: +~~~~~~~~~~~~~~~~~~ + + * IMPORTANT: the default compiled-in cipher parameters changed + plain mode: aes-cbc-essiv:sha256 (default is backward incompatible!). + LUKS mode: aes-cbc-essiv:sha256 (only key size increased) + In both modes is now default key size 256bits. + + * Default compiled-in parameters are now configurable through configure options: + --with-plain-* / --with-luks1-* (see configure --help) + + * If you need backward compatible defaults for distribution use + configure --with-plain-mode=cbc-plain --with-luks1-keybits=128 + + Default compiled-in modes are printed in "cryptsetup --help" output. + + * Change in iterations count (LUKS): + The slot and key digest iteration minimum count is now 1000. + The key digest iteration count is calculated from iteration time (approx 1/8 of req. time). + For more info about above items see discussion here: http://tinyurl.com/yaug97y + + * New libcryptsetup API (documented in libcryptsetup.h). + + The old API (using crypt_options struct) is still available but will remain + frozen and not used for new functions. + Soname of library changed to libcryptsetup.so.1.0.0. + (But only recompilation should be needed for old programs.) + + The new API provides much more flexible operation over LUKS device for + applications, it is preferred that new applications will use libcryptsetup + and not wrapper around cryptsetup binary. + + * New luksHeaderBackup and luksHeaderRestore commands. + + These commands allows binary backup of LUKS header. + Please read man page about possible security issues with backup files. + + * New luksSuspend (freeze device and wipe key) and luksResume (with provided passphrase). + + luksSuspend wipe encryption key in kernel memory and set device to suspend + (blocking all IO) state. This option can be used for situations when you need + temporary wipe encryption key (like suspend to RAM etc.) + Please read man page for more information. + + * New --master-key-file option for luksFormat and luksAddKey. + + User can now specify pre-generated master key in file, which allows regenerating + LUKS header or add key with only master key knowledge. + + * Uses libgcrypt and enables all gcrypt hash algorithms for LUKS through -h luksFormat option. + + Please note that using different hash for LUKS header make device incompatible with + old cryptsetup releases. + + * Introduces --debug parameter. + + Use when reporting bugs (just run cryptsetup with --debug and attach output + to issue report.) Sensitive data are never printed to this log. + + * Moves command successful messages to verbose level. + + * Requires device-mapper library and libgcrypt to build. + + * Uses dm-uuid for all crypt devices, contains device type and name now. + + * Removes support for dangerous non-exclusive option + (it is ignored now, LUKS device must be always opened exclusive) + +Other changes: +~~~~~~~~~~~~~~ + * Fixed localization to work again. Also cryptsetup is now translated by translationproject.org. + * Fix some libcryptsetup problems, including + * exported symbols and versions in libcryptsetup (properly use versioned symbols) + * Add crypt_log library function. + * Add CRYPT_ prefix to enum defined in libcryptsetup.h. + * Move duplicate Command failed message to verbose level (error is printed always). + * Fix several problems in build system + * use autopoint and clean gettext processing. + * Check in configure if selinux libraries are required in static version. + * Fix build for non-standard location of gcrypt library. + * Add temporary debug code to find processes locking internal device. + * Fix error handling during reading passphrase. + * Fail passphrase read if piped input no longer exists. + * Fix man page to not require --size which expands to device size by default. + * Clean up Makefiles and configure script. + * Try to read first sector from device to properly check that device is ready. + * Move memory locking and dm initialization to command layer. + * Increase priority of process if memory is locked. + * Add log macros and make logging more consistent. + * Keyfile now must be provided by path, only stdin file descriptor is used (api only). + * Do not call isatty() on closed keyfile descriptor. + * Move key slot manipulation function into LUKS specific code. + * Replace global options struct with separate parameters in helper functions. + * Implement old API calls using new functions. + * Allow using passphrase provided in options struct for LuksOpen. + * Allow restrict keys size in LuksOpen. + * Fix errors when compiled with LUKS_DEBUG. + * Print error when getline fails. + * Completely remove internal SHA1 implementation code, not needed anymore. + * Pad luks header to 512 sector size. + * Rework read/write blockwise to not split operation to many pieces. + * Use posix_memalign if available. + * Fix segfault if provided slot in luksKillslot is invalid. + * Remove unneeded timeout when remove of temporary device succeeded. diff --git a/docs/v1.1.1-ReleaseNotes b/docs/v1.1.1-ReleaseNotes new file mode 100644 index 0000000..e85107c --- /dev/null +++ b/docs/v1.1.1-ReleaseNotes @@ -0,0 +1,47 @@ +Cryptsetup 1.1.1 Release Notes +============================== + +Changes since version 1.1.1-rc2 +* Fix luksClose error if underlying device is LVM logical volume. + +Changes since version 1.1.1-rc1 +* Fix automatic dm-crypt module loading. + +Changes since version 1.1.0 + +Important changes: +~~~~~~~~~~~~~~~~~~ + +* Detects and use device-mapper udev support if available. + + This should allow synchronisation with udev rules and avoid races with udev. + + If package maintainer want to use old, direct libdevmapper device node creation, + use configure option --disable-udev. + +* Supports device topology detection for data alignment. + + If kernel provides device topology ioctl calls, the LUKS data area + alignment is automatically set to optimal value. + + This means that stacked devices (like LUKS over MD/LVM) + should use the most optimal data alignment. + + (You can still overwrite this calculation using --align-payload option.) + +* Prefers some device paths in status display. + (So status command will try to find top level device name, like /dev/sdb.) + +* Fix package config file to use proper package version. + +Other changes: +~~~~~~~~~~~~~~ +* Fix luksOpen reading of passphrase on stdin (if "-" keyfile specified). +* Fix isLuks to initialise crypto backend (blkid instead is suggested anyway). +* Properly initialise crypto backend in header backup/restore commands. +* Do not verify unlocking passphrase in luksAddKey command. +* Allow no hash specification in plain device constructor - user can provide volume key directly. +* Try to use pkgconfig for device mapper library in configuration script. +* Add some compatibility checks and disable LUKS suspend/resume if not supported. +* Rearrange tests, "make check" now run all available test for package. +* Avoid class C++ keyword in library header. diff --git a/docs/v1.1.2-ReleaseNotes b/docs/v1.1.2-ReleaseNotes new file mode 100644 index 0000000..9931f05 --- /dev/null +++ b/docs/v1.1.2-ReleaseNotes @@ -0,0 +1,33 @@ +== Cryptsetup 1.1.2 Release Notes == + +This release fixes a regression (introduced in 1.1.1 version) in handling +key files containing new line characters (affects only files read from +standard input). + +Cryptsetup can accept passphrase on stdin (standard input). + +Handling of new line (\n) character is defined by input specification: + + * if keyfile is specified as "-" (using --key-file=- of by "-" positional argument + in luksFormat and luksAddKey, like cat file | cryptsetup --key-file=- ), + input is processed as normal binary file and no new line is interpreted. + + * if there is no key file specification (with default input from stdin pipe + like echo passphrase | cryptsetup ) input is processed as input from terminal, + reading will stop after new line is detected. + +Moreover, luksFormat now understands --key-file (in addition to positional key +file argument). + +N.B. Using of standard input and pipes for passphrases should be avoided if possible, +cryptsetup have no control of used pipe buffers between commands in scripts and cannot +guarantee that all passphrase/key-file buffers are properly wiped after use. + +=== changes since version 1.1.1 === + + * Fix luksFormat/luksOpen reading passphrase from stdin and "-" keyfile. + * Support --key-file/-d option for luksFormat. + * Fix description of --key-file and add --verbose and --debug options to man page. + * Add verbose log level and move unlocking message there. + * Remove device even if underlying device disappeared (remove, luksClose). + * Fix (deprecated) reload device command to accept new device argument. diff --git a/docs/v1.1.3-ReleaseNotes b/docs/v1.1.3-ReleaseNotes new file mode 100644 index 0000000..94ee73e --- /dev/null +++ b/docs/v1.1.3-ReleaseNotes @@ -0,0 +1,13 @@ +== Cryptsetup 1.1.3 Release Notes == + +=== changes since version 1.1.2 === + +* Fix device alignment ioctl calls parameters. + (Device alignment code was not working properly on some architectures like ppc64.) + +* Fix activate_by_* API calls to handle NULL device name as documented. + (To enable check of passphrase/keyfile using libcryptsetup without activating the device.) + +* Fix udev support for old libdevmapper with not compatible definition. + +* Added Polish translation file. diff --git a/docs/v1.2.0-ReleaseNotes b/docs/v1.2.0-ReleaseNotes new file mode 100644 index 0000000..77fbedf --- /dev/null +++ b/docs/v1.2.0-ReleaseNotes @@ -0,0 +1,126 @@ +Cryptsetup 1.2.0 Release Notes +============================== + +Changes since version 1.2.0-rc1 + + * Fix crypt_activate_by_keyfile() to work with PLAIN devices. + * Fix plain create command to properly handle keyfile size. + * Update translations. + +Changes since version 1.1.3 + +Important changes +~~~~~~~~~~~~~~~~~ + + * Add text version of *FAQ* (Frequently Asked Questions) to distribution. + + * Add selection of random/urandom number generator for luksFormat + (option --use-random and --use-urandom). + + (This affects only long term volume key in *luksFormat*, + not RNG used for salt and AF splitter). + + You can also set the default to /dev/random during compilation with + --enable-dev-random. Compiled-in default is printed in --help output. + + Be very careful before changing default to blocking /dev/random use here. + + * Fix *luksRemoveKey* to not ask for remaining keyslot passphrase, + only for removed one. + + * No longer support *luksDelKey* (replaced with luksKillSlot). + * if you want to remove particular passphrase, use *luksKeyRemove* + * if you want to remove particular keyslot, use *luksKillSlot* + + Note that in batch mode *luksKillSlot* allows removing of any keyslot + without question, in normal mode requires passphrase or keyfile from + other keyslot. + + * *Default alignment* for device (if not overridden by topology info) + is now (multiple of) *1MiB*. + This reflects trends in storage technologies and aligns to the same + defaults for partitions and volume management. + + * Allow explicit UUID setting in *luksFormat* and allow change it later + in *luksUUID* (--uuid parameter). + + * All commands using key file now allows limited read from keyfile using + --keyfile-size and --new-keyfile-size parameters (in bytes). + + This change also disallows overloading of --key-size parameter which + is now exclusively used for key size specification (in bits.) + + * *luksFormat* using pre-generated master key now properly allows + using key file (only passphrase was allowed prior to this update). + + * Add --dump-master-key option for *luksDump* to perform volume (master) + key dump. Note that printed information allows accessing device without + passphrase so it must be stored encrypted. + + This operation is useful for simple Key Escrow function (volume key and + encryption parameters printed on paper on safe place). + + This operation requires passphrase or key file. + + * The reload command is no longer supported. + (Use dmsetup reload instead if needed. There is no real use for this + function except explicit data corruption:-) + + * Cryptsetup now properly checks if underlying device is in use and + disallows *luksFormat*, *luksOpen* and *create* commands on open + (e.g. already mapped or mounted) device. + + * Option --non-exclusive (already deprecated) is removed. + +Libcryptsetup API additions: + + * new functions + * crypt_get_type() - explicit query to crypt device context type + * crypt_resize() - new resize command using context + * crypt_keyslot_max() - helper to get number of supported keyslots + * crypt_get_active_device() - get active device info + * crypt_set/get_rng_type() - random/urandom RNG setting + * crypt_set_uuid() - explicit UUID change of existing device + * crypt_get_device_name() - get underlying device name + + * Fix optional password callback handling. + + * Allow one to activate by internally cached volume key immediately after + crypt_format() without active slot (for temporary devices with + on-disk metadata) + + * libcryptsetup is binary compatible with 1.1.x release and still + supports legacy API calls + + * cryptsetup binary now uses only new API calls. + + * Static compilation of both library (--enable-static) and cryptsetup + binary (--enable-static-cryptsetup) is now properly implemented by common + libtool logic. + + Prior to this it produced miscompiled dynamic cryptsetup binary with + statically linked libcryptsetup. + + The static binary is compiled as src/cryptsetup.static in parallel + with dynamic build if requested. + +Other changes +~~~~~~~~~~~~~ + * Fix default plain password entry from terminal in activate_by_passphrase. + * Initialize volume key from active device in crypt_init_by_name() + * Fix cryptsetup binary exit codes. + 0 - success, otherwise fail + 1 - wrong parameters + 2 - no permission + 3 - out of memory + 4 - wrong device specified + 5 - device already exists or device is busy + * Remove some obsolete info from man page. + * Add more regression tests for commands. + * Fix possible double free when handling master key file. + * Fix pkg-config use in automake scripts. + * Wipe iteration and salt after luksKillSlot in LUKS header. + * Rewrite file differ test to C (and fix it to really work). + * Do not query non-existent device twice (cryptsetup status /dev/nonexistent). + * Check if requested hash is supported before writing LUKS header. + * Fix problems reported by clang scan-build. diff --git a/docs/v1.3.0-ReleaseNotes b/docs/v1.3.0-ReleaseNotes new file mode 100644 index 0000000..b7ae977 --- /dev/null +++ b/docs/v1.3.0-ReleaseNotes @@ -0,0 +1,101 @@ +Cryptsetup 1.3.0 Release Notes +============================== + +Changes since version 1.2.0 + +Important changes +~~~~~~~~~~~~~~~~~ + * Several userspace crypto backends support + + cryptsetup now supports generic crypto backend interface which allows + compile package with various crypto libraries, these are already implemented: + + * gcrypt (default, used in previous versions) + * OpenSSL + * NSS (because of missing ripemd160 it cannot provide full backward compatibility) + * kernel userspace API (provided by kernel 2.6.38 and above) + (Note that kernel userspace backend is very slow for this type of operation. + But it can be useful for embedded systems, because you can avoid userspace + crypto library completely.) + + Backend is selected during configure time, using --with-crypto_backend option. + + configure --with-crypto_backend=BACKEND (gcrypt/openssl/nss/kernel) [gcrypt] + + Note that performance checked (iterations) in LUKS header will cause that + real iteration time will differ with different backends. + (There are huge differences in speed between libraries.) + + * Cryptsetup now automatically allocates loopback device (/dev/loop) if device + argument is file and not plain device. + + This require Linux kernel 2.6.25 and above (which implements loop autoclear flag). + + You can see backing file in cryptsetup status output if underlying device is loopback. + + * Introduce maximum default keyfile size, add configure option, visible in --help. + + Cryptsetup now fails if read from keyfile exceeds internal limit. + You can always specify keyfile size (overrides limit) by using --keyfile-size option. + + * Adds luksChangeKey command + + cryptestup luksChangeKey --key-file [--key-slot X] + cryptestup luksChangeKey [--key-slot X] (for passphrase change) + + This command allows passphrase/keyfile change in one step. If no key slot is + specified (and there is still free key slot on device) new slot is allocated before + the old is purged. + + If --key-slot option is specified (or there is no free slot) command will overwrite + existing slot. + WARNING: Be sure you have another slot active or header backup when using explicit + key slot (so you can unlock the device even after possible media failure). + + * Adds compatible support for loop-AES encryption type in loopaesOpen command. + + Linux dm-crypt in 2.6.38 and above supports loop-AES compatible mapping + (including multi-key and special CBC mode, all three modes are supported). + + If you have raw loop-AES keyfile (text file with uuencoded per-line keys), you can + access loop-AES volume using + cryptsetup loopaesOpen [--key-size 128] --key-file + + If you are using GPG encrypted keyfile + gpg --decrypt | cryptsetup loopaesOpen --key-file=- + + Do not forget to specify key size. Version and hash is automatically detected + according to number of lines in key file. For special configuration you can + override IV sector offset using --skip option, device offset with --offset + and hash algorithm using --hash, see man page for details. + + Please note that loopAES dm-crypt mode is provided for compatibility reasons + (so you do not need to patch kernel and util-linux to map existing volumes) + but it is not, and never will be, optimized for speed. + It is experimental feature for now. + + * Require the whole key read from keyfile in create command (regression in 1.2.0). + + * WARNING: This is the last cryptsetup release which supports library with + old API (using struct crypt_options). + These calls are deprecated since 1.1.0 and AFAIK no application + is using it in recent distros. Removing compatible code will allow + new features to be implemented easily. + +Other changes +~~~~~~~~~~~~~ + * Lock memory also in luksDump command. + * Fix return code when passphrase is read from pipe. + * Increase libcryptsetup version (loopAES change), still fully backward compatible. + * Fixes static build (--disable-static-cryptsetup now works properly). + * Supports secure data flag for device-mapper ioctl (will be in 2.6.39, + forcing kernel to wipe all ioctl buffers with possible key data). + To enable this flag you need new device-mapper library, in LVM2 2.02.84. + * Add copyright texts into some files and adds GPL exception allowing + to distribute resulting binaries linked with OpenSSL. + * Update FAQ. + * Fix message when locking memory fails. + * Fix luksAddKey return code if master key is used. + * Update some text files in distributions. + * Add docs directory with Release Notes archive. + * Do not hardcode loopback device name in tests, use internal loopback library. diff --git a/docs/v1.3.1-ReleaseNotes b/docs/v1.3.1-ReleaseNotes new file mode 100644 index 0000000..8b2d1dd --- /dev/null +++ b/docs/v1.3.1-ReleaseNotes @@ -0,0 +1,14 @@ +Cryptsetup 1.3.1 Release Notes +============================== + +Changes since version 1.3.0 + + * Fix keyfile=- processing in create command (regression in 1.3.0). + + * Simplify device path status check (use /sys and do not scan /dev). + + * Do not ignore device size argument for create command (regression in 1.2.0). + + * Fix error paths in blockwise code and lseek_write call. + + * Add optional Nettle crypto backend support. diff --git a/docs/v1.4.0-ReleaseNotes b/docs/v1.4.0-ReleaseNotes new file mode 100644 index 0000000..bef4e74 --- /dev/null +++ b/docs/v1.4.0-ReleaseNotes @@ -0,0 +1,131 @@ +Cryptsetup 1.4.0 Release Notes +============================== + +Changes since version 1.3.1 + +Important changes +~~~~~~~~~~~~~~~~~ + +WARNING: This release removes old deprecated API from libcryptsetup + (all functions using struct crypt_options). + + This require libcrypsetup version change and + rebuild of applications using cryptsetup library. + All new API symbols are backward compatible. + +* If device is not rotational disk, cryptsetup no longer tries + to wipe keyslot with Gutmann algorithm for magnetic media erase + but simply rewrites area once by random data. + +* The on-disk LUKS header can now be detached (e.g. placed on separate + device or in file) using new --header option. + + This option is only relevant for LUKS devices and can be used in + luksFormat, luksOpen, luksSuspend, luksResume and resize commands. + + If used with luksFormat the --align-payload option is taken + as absolute sector alignment on ciphertext device and can be zero. + + Example: + Create LUKS device with ciphertext device on /dev/sdb and header + on device /dev/sdc. Use all space on /dev/sdb (no reserved area for header). + + cryptsetup luksFormat /dev/sdb --header /dev/sdc --align-payload 0 + + Activate such device: + cryptsetup luksOpen /dev/sdb --header /dev/sdc test_disk + + You can use file for LUKS header (loop device will be used while + manipulating with such detached header), just you have to create + large enough file in advance. + + dd if=/dev/zero of=/mnt/luks_header bs=1M count=4 + cryptsetup luksFormat /dev/sdb --header /mnt/luks_header --align-payload 0 + + Activation is the same as above. + + cryptsetup luksOpen /dev/sdb --header /mnt/luks_header test_disk + + All keyslot operations need to be run on _header_ not on ciphertext device, + an example: + + cryptsetup luksAddKey /mnt/luks_header + + If you do not use --align-payload 0, you can later restore LUKS header + on device itself (and use it as normal LUKS device without detached header). + + WARNING: There is no possible check that specified ciphertext device + matches detached on-disk header. Use with care, it can destroy + your data in case of a mistake. + + WARNING: Storing LUKS header in a file means that anti-forensic splitter + cannot properly work (there is filesystem allocation layer between + header and disk). + +* Support --allow-discards option to allow discards/TRIM requests. + + Since kernel 3.1, dm-crypt devices optionally (not by default) support + block discards (TRIM) commands. + If you want to enable this operation, you have to enable it manually + on every activation using --allow-discards + + cryptsetup luksOpen --allow-discards /dev/sdb test_disk + + WARNING: There are several security consequences, please read at least + http://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html + before you enable it. + +* Add --shared option for creating non-overlapping crypt segments. + + The --shared options checks that mapped segments are not overlapping + and allows non-exclusive access to underlying device. + Only plain crypt devices can be used in this mode. + + Example - map 64M of device disk and following 32 M area as another disk. + + cryptsetup create outer_disk /dev/sdb --offset 0 --size 65536 + cryptsetup create inner_disk /dev/sdb --offset 65536 --size 32768 --shared + + (It can be used to simulate trivial hidden disk concepts.) + +libcryptsetup API changes: + * Added options to support detached metadata device + crypt_init_by_name_and_header() + crypt_set_data_device() + * Add crypt_last_error() API call. + * Fix plain crypt format parameters to include size option. + * Add crypt_get_iv_offset() function. + + * Remove old API functions (all functions using crypt_options). + +* Support key-slot option for luksOpen (use only explicit keyslot). + + You can now specify key slot in luksOpen and limit checking + only to specified slot. + +* Support retries and timeout parameters for luksSuspend. + (The same way as in luksOpen.) + +* Add doxygen-like documentation (it will be available on project page later). + (To generate it manually run doxygen in docs directory.) + +Other changes +~~~~~~~~~~~~~ +* Fix crypt_load to properly check device size. +* Do not allow context format of already formatted device. +* Do not allow key retrieval while suspended (key could be wiped). +* Do not allow suspend for non-LUKS devices. +* Fix luksKillSLot exit code if slot is inactive or invalid. +* Fix exit code if passphrases do not match in luksAddKey. +* Fix return code for status command when device doesn't exists. +* Fix verbose messages in isLuks command. +* Support Nettle 2.4 crypto backend (supports ripemd160). +* Add LUKS on-disk format description into package. +* Enhance check of device size before writing LUKS header. +* Add more paranoid checks for LUKS header and keyslot attributes. +* Use new /dev/loop-control (kernel 3.1) if possible. +* Remove hash/hmac restart from crypto backend and make it part of hash/hmac final. +* Improve check for invalid offset and size values. +* Revert default initialisation of volume key in crypt_init_by_name(). +* Add more regression tests. +* Add some libcryptsetup example files (see docs/examples). diff --git a/docs/v1.4.1-ReleaseNotes b/docs/v1.4.1-ReleaseNotes new file mode 100644 index 0000000..ea68cb8 --- /dev/null +++ b/docs/v1.4.1-ReleaseNotes @@ -0,0 +1,25 @@ +Cryptsetup 1.4.1 Release Notes +============================== + +Changes since version 1.4.0 + +* Merge experimental Python cryptsetup (pycryptsetup) binding. + + This option is disabled by default, you can enable build of Python binding + with --enable--python configure switch. + + Note that binding currently covers only partial libcryptsetup functions, + mainly LUKS device handling needed for Anaconda installer. + Until now provided separately as python-cryptsetup. + Thanks to Martin Sivak for the code. + + See python subdirectory for more info. + + Python binding code is experimental for now, no stable API guarantee. + +* Fix crypt_get_volume_key_size() for plain device. + (cryptsetup status reported zero key size for plain crypt devices). + +* Fix typo in set_iteration_time API call (old name remains for compatibility reasons). + +* Fix FSF address in license and add LGPL license text. diff --git a/docs/v1.4.2-ReleaseNotes b/docs/v1.4.2-ReleaseNotes new file mode 100644 index 0000000..a3c2912 --- /dev/null +++ b/docs/v1.4.2-ReleaseNotes @@ -0,0 +1,44 @@ +Cryptsetup 1.4.2 Release Notes +============================== + +Changes since version 1.4.1 + +* Add --keyfile-offset and --new-keyfile-offset parameters to API and CLI. + These options can be used to skip start of keyfile or device used as keyfile. + +* Add repair command and crypt_repair() for known LUKS metadata problems repair. + + Some well-known LUKS metadata corruptions are easy to repair, this + command should provide a way to fix these problems. + + Always create binary backup of header device before running repair, + (only 4kB - visible header) for example by using dd: + dd if=/dev/ of=repair_bck.img bs=1k count=4 + + Then you can try to run repair: + cryptsetup repair + + Note, not all problems are possible to repair and if keyslot or some header + parameters are overwritten, device is lost permanently. + +* Fix header check to support old (cryptsetup 1.0.0) header alignment. + (Regression in 1.4.0) + +* Allow one to specify --align-payload only for luksFormat. + +* Add --master-key-file option to luksOpen (open using volume key). + +* Support UUID= format for device specification. + You can open device by UUID (only shortcut to /dev/disk/by-uuid/ symlinks). + +* Support password verification with quiet flag if possible. (1.2.0) + Password verification can be still possible if input is terminal. + +* Fix retry if entered passphrases (with verify option) do not match. + (It should retry if requested, not fail.) + +* Fix use of empty keyfile. + +* Fix error message for luksClose and detached LUKS header. + +* Allow --header for status command to get full info with detached header. diff --git a/docs/v1.4.3-ReleaseNotes b/docs/v1.4.3-ReleaseNotes new file mode 100644 index 0000000..16792a5 --- /dev/null +++ b/docs/v1.4.3-ReleaseNotes @@ -0,0 +1,62 @@ +Cryptsetup 1.4.3 Release Notes +============================== + +Changes since version 1.4.2 + +* Fix readonly activation if underlying device is readonly (1.4.0). + +* Fix loop mapping on readonly file. + +* Include stddef.h in libdevmapper.h (size_t definition). + +* Fix keyslot removal for device with 4k hw block (1.4.0). +(Wipe keyslot failed in this case.) + +* Relax --shared flag to allow mapping even for overlapping segments. + + The --shared flag (and API CRYPT_ACTIVATE_SHARED flag) is now able + to map arbitrary overlapping area. From API it is even usable + for LUKS devices. + It is user responsibility to not cause data corruption though. + + This allows e.g. scubed to work again and also allows some + tricky extensions later. + +* Allow empty cipher (cipher_null) for testing. + + You can now use "null" (or directly cipher_null-ecb) in cryptsetup. + This means no encryption, useful for performance tests + (measure dm-crypt layer overhead). + +* Switch on retry on device remove for libdevmapper. + Device-mapper now retry removal if device is busy. + +* Allow "private" activation (skip some udev global rules) flag. + Cryptsetup library API now allows one to specify CRYPT_ACTIVATE_PRIVATE, + which means that some udev rules are not processed. + (Used for temporary devices, like internal keyslot mappings where + it is not desirable to run any device scans.) + +* This release also includes some Red Hat/Fedora specific extensions +related to FIPS140-2 compliance. + +In fact, all these patches are more formal changes and are just subset +of building blocks for FIPS certification. See FAQ for more details +about FIPS. + +FIPS extensions are enabled by using --enable-fips configure switch. + +In FIPS mode (kernel booted with fips=1 and gcrypt in FIPS mode) + + - it provides library and binary integrity verification using + libfipscheck (requires pre-generated checksums) + + - it uses FIPS approved RNG for encryption key and salt generation + (note that using /dev/random is not formally FIPS compliant RNG). + + - only gcrypt crypto backend is currently supported in FIPS mode. + +The FIPS RNG requirement for salt comes from NIST SP 800-132 recommendation. +(Recommendation for Password-Based Key Derivation. Part 1: Storage Applications. +http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf) +LUKS should be aligned to this recommendation otherwise. diff --git a/docs/v1.5.0-ReleaseNotes b/docs/v1.5.0-ReleaseNotes new file mode 100644 index 0000000..9f1e1d1 --- /dev/null +++ b/docs/v1.5.0-ReleaseNotes @@ -0,0 +1,241 @@ +Cryptsetup 1.5.0 Release Notes +============================== + +This release covers mainly inclusion of: + + * Veritysetup tool (and related libcryptsetup extensions for dm-verity). + + * Experimental cryptsetup-reencrypt tool (LUKS offline reencryption). + +Changes since version 1.5.0-rc2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * Add --device-size option for reencryption tool. + + * Switch to use unit suffix for --reduce-device-size option. + + * Remove open device debugging feature (no longer needed). + + * Fix library name for FIPS check. + + * Add example of using reencryption inside dracut (see misc/dracut). + +Changes since version 1.5.0-rc1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Introduce cryptsetup-reencrypt - experimental offline LUKS reencryption tool. + +! cryptsetup-reencrypt tool is EXPERIMENTAL +! ALWAYS BE SURE YOU HAVE RELIABLE BACKUP BEFORE USING THIS TOOL + +This tool tries to simplify situation when you need to re-encrypt the whole +LUKS device in situ (without need to move data elsewhere). + +This can happen for example when you want to change volume (master) key, +encryption algorithm, or other encryption parameter. + +Cryptsetup-reencrypt can even optionally shift data on device +(reducing data device size - you need some free space at the end of device). + +In general, cryptsetup-reencrypt can be used to + + - re-generate volume key + - change arbitrary encryption parameters + - add encryption to not yet encrypted drive + +Side effect of reencryption is that final device will contain +only ciphertext (for all sectors) so even if device was not properly +wiped by random data, after reencryption you cannot distinguish +which sectors are used. +(Reencryption is done always for the whole device.) + +There are for sure bugs, please TEST IT IN TEST ENVIRONMENT before +use for your data. + +This tool is not resistant to HW and kernel failures - hw crash +will cause serious data corruption. + +You can enable compilation of this tool with --enable-cryptsetup-reencrypt +configure option (it is switched off by default). +(Tool requires libcryptsetup 1.4.3 and later.) + +You have to provide all keyslot passphrases or use --keyslot-option +(then all other keyslots will be disabled). + +EXAMPLES (from man page) + +Reencrypt /dev/sdb1 (change volume key) + # cryptsetup-reencrypt /dev/sdb1 + +Reencrypt and also change cipher and cipher mode + # cryptsetup-reencrypt /dev/sdb1 -c aes-xts-plain64 + + Note: if you are changing key size, there must be enough space + for keyslots in header or you have to use --reduce-device size and + reduce fs in advance. + +Add LUKS encryption to not yet encrypted device + First, be sure you have space added to disk. + Or, alternatively, shrink filesystem in advance. + + Here we need 4096 512-bytes sectors (enough for 2x128 bit key). + + # fdisk -u /dev/sdb # move sdb1 partition end + 4096 sectors + + # cryptsetup-reencrypt /dev/sdb1 --new --reduce-device-size 4096 + +There are some options which can improve performance (depends on system), +namely --use-directio (use direct IO for all operations) can be faster +on some systems. See man page. + +Progress and estimated time is printed during reencryption. + +You can suspend reencryption (using ctrl+c or term signal). +To continue reencryption you have to provide only +the device parameter (offset is stored in temporary log file). + +Please note LUKS device is marked invalid during reencryption and +you have to retain tool temporary files until reencryption finishes. + +Temporary files are LUKS-.[log|org|new] + +Other changes +~~~~~~~~~~~~~ + + * Fix luks-header-from-active script (do not use LUKS header on-disk, add UUID). + + * Add --test-passphrase option for luksOpen (check passphrase only). + + * Fix parsing of hexadecimal string (salt or root hash) in veritysetup. + +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 + Formats (calculates all hash areas according to ). + This is initial command to prepare device for later verification. + + veritysetup create + Creates (activates) a dm-verity mapping with backed by device + and using for in-kernel verification. + + veritysetup verify + Verifies data in userspace (no kernel device is activated). + + veritysetup remove + Removes activated device from kernel (similar to dmsetup remove). + + veritysetup status + Reports status for the active kernel dm-verity device. + + veritysetup dump + 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 diff --git a/docs/v1.5.1-ReleaseNotes b/docs/v1.5.1-ReleaseNotes new file mode 100644 index 0000000..7202a8c --- /dev/null +++ b/docs/v1.5.1-ReleaseNotes @@ -0,0 +1,32 @@ +Cryptsetup 1.5.1 Release Notes +============================== + +Changes since version 1.5.0 + +* The libcryptsetup library now tries to initialize device-mapper backend and + loop devices only if they are really needed (lazy initializations). + This allows some operations to be run by a non-root user. + + (Unfortunately LUKS header keyslot operations still require temporary dm-crypt + device and device-mapper subsystem is available only to superuser.) + + Also clear error messages are provided if running as non-root user and + operation requires privileged user. + +* Veritysetup can be now used by a normal user for creating hash image to file + and also it can create hash image if doesn't exist. + (Previously it required pre-allocated space.) + +* Added crypt_keyslot_area() API call which allows external tools + to get exact keyslot offsets and analyse content. + + An example of a tool that searches the keyslot area of a LUKS container + for positions where entropy is low and hence there is a high probability + of damage is in misc/kesylot_checker. + (Thanks to Arno Wagner for the code.) + +* Optimized seek to keyfile-offset if key offset is large. + +* Fixed luksHeaderBackup for very old v1.0 unaligned LUKS headers. + +* Various fixes for problems found by a several static analysis tools. diff --git a/docs/v1.6.0-ReleaseNotes b/docs/v1.6.0-ReleaseNotes new file mode 100644 index 0000000..8ee64a0 --- /dev/null +++ b/docs/v1.6.0-ReleaseNotes @@ -0,0 +1,261 @@ +Cryptsetup 1.6.0 Release Notes +============================== + +Changes since version 1.6.0-rc1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + * Change LUKS default cipher to use XTS encryption mode, + aes-xts-plain64 (i.e. using AES128-XTS). + + XTS mode becomes standard in hard disk encryption. + + You can still use any old mode: + - compile cryptsetup with old default: + configure --with-luks1-cipher=aes --with-luks1-mode=cbc-essiv:sha256 --with-luks1-keybits=256 + - format LUKS device with old default: + cryptsetup luksFormat -c aes-cbc-essiv:sha256 -s 256 + + + * Skip tests and fix error messages if running on old systems (or with old kernel). + + * Rename configure.in to configure.ac and fix issues with new automake and pkgconfig + and --disable-kernel_crypto option to allow compilation with old kernel headers. + + * Allow repair of 512 bits key header. + + * Fix status of device if path argument is used and fix double path prefix + for non-existent device path. + + +Changes since version 1.5.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Important changes +~~~~~~~~~~~~~~~~~ + + * Cryptsetup and libcryptsetup is now released under GPLv2+ + (GPL version 2 or any later). + Some internal code handling files (loopaes, verity, tcrypt + and crypto backend wrapper) are LGPLv2+. + + Previously code was GPL version 2 only. + + + * Introducing new unified command open and close. + + Example: + cryptsetup open --type plain|luks|loopaes|tcrypt + (type defaults to luks) + + with backward-compatible aliases plainOpen, luksOpen, loopaesOpen, + tcryptOpen. Basically "open --type xyz" has alias "xyzOpen". + + The "create" command (plain device create) is DEPRECATED but will + be still supported. + (This command is confusing because of switched arguments order.) + + The close command is generic command to remove mapping and have + backward compatible aliases (remove, luksClose, ...) which behaves + exactly the same. + + While all old syntax is still supported, I strongly suggest to use + new command syntax which is common for all device types (and possible + new formats added in future). + + + * cryptsetup now support directly TCRYPT (TrueCrypt and compatible tc-play) + on-disk format + (Code is independent implementation not related to original project). + + Only dump (tcryptDump command) and activation (open --type tcrypt or tcryptOpen) + of TCRYPT device are supported. No header changes are supported. + + It is intended to easily access containers shared with other operating systems + without need to install 3rd party software. For native Linux installations LUKS + is the preferred format. + + WARNING: TCRYPT extension requires kernel userspace crypto API to be + available (introduced in Linux kernel 2.6.38). + If you are configuring kernel yourself, enable "User-space interface + for symmetric key cipher algorithms" in "Cryptographic API" section + (CRYPTO_USER_API_SKCIPHER .config option). + + Because TCRYPT header is encrypted, you have to always provide valid + passphrase and keyfiles. Keyfiles are handled exactly the same as in original + format (basically, first 1MB of every keyfile is mixed using CRC32 into pool). + + Cryptsetup should recognize all TCRYPT header variants ever released, except + legacy cipher chains using LRW encryption mode with 64 bits encryption block + (namely Blowfish in LRW mode is not recognized, this is limitation of kernel + crypto API). + + Device activation is supported only for LRW/XTS modes (again, limitation + of kernel dmcrypt which do not implements TCRYPT extensions to CBC mode). + (So old containers cannot be activated, but you can use libcryptsetup + for lost password search, example of such code is included in misc directory.) + + Hidden header are supported using --tcrypt-hidden option, system encryption + using --tcrypt-system option. + + For detailed description see man page. + + EXAMPLE: + * Dump device parameters of container in file: + + # cryptsetup tcryptDump tst + Enter passphrase: + + TCRYPT header information for tst + Version: 5 + Driver req.: 7 + Sector size: 512 + MK offset: 131072 + PBKDF2 hash: sha512 + Cipher chain: serpent-twofish-aes + Cipher mode: xts-plain64 + MK bits: 1536 + + You can also dump master key using --dump-master-key. + Dump does not require superuser privilege. + + * Activation of this container + + # cryptsetup tcryptOpen tst tcrypt_dev + Enter passphrase: + (Chain of dmcrypt devices is activated as /dev/mapper/tcrypt_dev.) + + * See status of active TCRYPT device + + # cryptsetup status tcrypt_dev + + /dev/mapper/tcrypt_dev is active. + type: TCRYPT + cipher: serpent-twofish-aes-xts-plain64 + keysize: 1536 bits + device: /dev/loop0 + loop: /tmp/tst + offset: 256 sectors + size: 65024 sectors + skipped: 256 sectors + mode: read/write + + * And plaintext filesystem now ready to mount + + # blkid /dev/mapper/tcrypt_dev + /dev/mapper/tcrypt_dev: SEC_TYPE="msdos" UUID="9F33-2954" TYPE="vfat" + + + * Add (optional) support for lipwquality for new LUKS passwords. + + If password is entered through terminal (no keyfile specified) + and cryptsetup is compiled with --enable-pwquality, default + system pwquality settings are used to check password quality. + + You can always override this check by using new --force-password option. + + For more info about pwquality project see http://libpwquality.fedorahosted.org/ + + + * Proper handle interrupt signals (ctrl+c and TERM signal) in tools + + Code should now handle interrupt properly, release and explicitly wipe + in-memory key materials on interrupt. + (Direct users of libcryptsetup should always call crypt_free() when + code is interrupted to wipe all resources. There is no signal handling + in library, it is up to the tool using it.) + + + * Add new benchmark command + + The "benchmark" command now tries to benchmark PBKDF2 and some block + cipher variants. You can specify you own parameters (--cipher/--key-size + for block ciphers, --hash for PBKDF2). + + See man page for detailed description. + + WARNING: benchmark command requires kernel userspace crypto API to be + available (introduced in Linux kernel 2.6.38). + If you are configuring kernel yourself, enable "User-space interface + for symmetric key cipher algorithms" in "Cryptographic API" section + (CRYPTO_USER_API_SKCIPHER .config option). + + EXAMPLE: + # cryptsetup benchmark + # Tests are approximate using memory only (no storage IO). + PBKDF2-sha1 111077 iterations per second + PBKDF2-sha256 53718 iterations per second + PBKDF2-sha512 18832 iterations per second + PBKDF2-ripemd160 89775 iterations per second + PBKDF2-whirlpool 23918 iterations per second + # Algorithm | Key | Encryption | Decryption + aes-cbc 128b 212.0 MiB/s 428.0 MiB/s + serpent-cbc 128b 23.1 MiB/s 66.0 MiB/s + twofish-cbc 128b 46.1 MiB/s 50.5 MiB/s + aes-cbc 256b 163.0 MiB/s 350.0 MiB/s + serpent-cbc 256b 23.1 MiB/s 66.0 MiB/s + twofish-cbc 256b 47.0 MiB/s 50.0 MiB/s + aes-xts 256b 190.0 MiB/s 190.0 MiB/s + serpent-xts 256b 58.4 MiB/s 58.0 MiB/s + twofish-xts 256b 49.0 MiB/s 49.5 MiB/s + aes-xts 512b 175.0 MiB/s 175.0 MiB/s + serpent-xts 512b 59.0 MiB/s 58.0 MiB/s + twofish-xts 512b 48.5 MiB/s 49.5 MiB/s + + Or you can specify cipher yourself: + # cryptsetup benchmark --cipher cast5-cbc-essiv:sha256 -s 128 + # Tests are approximate using memory only (no storage IO). + # Algorithm | Key | Encryption | Decryption + cast5-cbc 128b 32.4 MiB/s 35.0 MiB/s + + WARNING: these tests do not use dmcrypt, only crypto API. + You have to benchmark the whole device stack and you can get completely + different results. But it is usable for basic comparison. + (Note for example AES-NI decryption optimization effect in example above.) + +Features +~~~~~~~~ + + * Do not maintain ChangeLog file anymore, see git log for detailed changes, + e.g. here http://code.google.com/p/cryptsetup/source/list + + * Move change key into library, add crypt_keyslot_change_by_passphrase(). + This change is useful mainly in FIPS mode, where we cannot + extract volume key directly from libcryptsetup. + + * Add verbose messages during reencryption. + + * Default LUKS PBKDF2 iteration time is now configurable. + + * Add simple cipher benchmarking API. + + * Add kernel skcipher backend. + + * Add CRC32 implementation (for TCRYPT). + + * Move PBKDF2 into crypto backend wrapper. + This allows use it in other formats, use library implementations and + also possible use of different KDF function in future. + + * New PBKDF2 benchmark using getrusage(). + +Fixes +~~~~~ + + * Avoid O_DIRECT open if underlying storage doesn't support it. + + * Fix some non-translated messages. + + * Fix regression in header backup (1.5.1) with container in file. + + * Fix blockwise read/write for end writes near end of device. + (was not used in previous versions) + + * Ignore setpriority failure. + + * Code changes to fix/ignore problems found by Coverity static analysis, including + - Get page size should never fail. + - Fix time of check/use (TOCTOU test) in tools + - Fix time of check/use in loop/wipe utils. + - Fix time of check/use in device utils. + + * Disallow header restore if context is non-LUKS device. diff --git a/docs/v1.6.1-ReleaseNotes b/docs/v1.6.1-ReleaseNotes new file mode 100644 index 0000000..8fdc7d0 --- /dev/null +++ b/docs/v1.6.1-ReleaseNotes @@ -0,0 +1,32 @@ +Cryptsetup 1.6.1 Release Notes +============================== + +Changes since version 1.6.0 + +* Fix loop-AES keyfile parsing. + Loop-AES keyfile should be text keyfile, reject keyfiles which + are not properly terminated. + +* Fix passphrase pool overflow for too long TCRYPT passphrase. + (Maximal TCRYPT passphrase length is 64 characters.) + +* Return EPERM (translated to exit code 2) for too long TCRYPT passphrase. + +* Fix deactivation of device when failed underlying node disappeared. + +* Fix API deactivate call for TCRYPT format and NULL context parameter. + +* Improve keyslot checker example documentation. + +* Report error message if deactivation fails and device is still busy. + +* Make passphrase prompts more consistent (and remove "LUKS" form prompt). + +* Fix some missing headers (compilation failed with alternative libc). + +* Remove not functional API UUID support for plain & loopaes devices. + (not persistent activation UUID). + +* Properly cleanup devices on interrupt in api-test. + +* Support all tests run if kernel is in FIPS mode. diff --git a/docs/v1.6.2-ReleaseNotes b/docs/v1.6.2-ReleaseNotes new file mode 100644 index 0000000..fba3990 --- /dev/null +++ b/docs/v1.6.2-ReleaseNotes @@ -0,0 +1,25 @@ +Cryptsetup 1.6.2 Release Notes +============================== + +Changes since version 1.6.1 + +* Print error and fail if more device arguments are present for isLuks command. + +* Fix cipher specification string parsing (found by gcc -fsanitize=address option). + +* Try to map TCRYPT system encryption through partition + (allows one to activate mapping when other partition on the same device is mounted). + +* Print a warning if system encryption is used and device is a partition. + (TCRYPT system encryption uses whole device argument.) + +* Disallow explicit small payload offset for LUKS detached header. + LUKS detached header only allows data payload 0 (whole data device is used) + or explicit offset larger than header + keyslots size. + +* Fix boundary condition for verity device that caused failure for certain device sizes. + +* Various fixes to documentation, including update FAQ, default modes + and TCRYPT description. + +* Workaround for some recent changes in automake (serial-tests). diff --git a/docs/v1.6.3-ReleaseNotes b/docs/v1.6.3-ReleaseNotes new file mode 100644 index 0000000..24254b8 --- /dev/null +++ b/docs/v1.6.3-ReleaseNotes @@ -0,0 +1,50 @@ +Cryptsetup 1.6.3 Release Notes +============================== + +Changes since version 1.6.2 + +* Fix cryptsetup reencryption tool to work properly + with devices using 4kB sectors. + +* Always use page size if running through loop device, + this fixes failures for external LUKS header and + filesystem requiring 4kB block size. + +* Fix TCRYPT system encryption mapping for multiple partitions. + Since this commit, one can use partition directly as device parameter. + If you need to activate such partition from image in file, + please first use map partitioned loop device (losetup -P) + on image. + (Cryptsetup require partition offsets visible in kernel sysfs + in this mode.) + +* Support activation of old TrueCrypt containers using CBC mode + and whitening (created in TrueCrypt version < 4.1). + This requires Linux kernel 3.13 or later. + (Containers with cascade CBC ciphers are not supported.) + +* Properly display keys in dump --dump-master-key command + for TrueCrypt CBC containers. + +* Rewrite cipher benchmark loop which was unreliable + on very fast machines. + +* Add warning if LUKS device was activated using non-cryptsetup + library which did not set UUID properly (e.g. cryptmount). + (Some commands, like luksSuspend, are not available then.) + +* Support length limitation also for plain (no hash) length. + This can be used for mapping problematic cryptosystems which + wipes some key (losetup sometimes set last 32 byte to zero, + which can be now configured as --hash plain:31 parameter). + +* Fix hash limit if parameter is not a number. + (The whole key was set to zero instead of command failure.) + +* Unify --key-slot behavior in cryptsetup_reencrypt tool. + +* Update dracut example scripts for system reencryption on first boot. + +* Add command line option --tcrypt-backup to access TCRYPT backup header. + +* Fix static compilation with OpenSSL. diff --git a/docs/v1.6.4-ReleaseNotes b/docs/v1.6.4-ReleaseNotes new file mode 100644 index 0000000..010ba5f --- /dev/null +++ b/docs/v1.6.4-ReleaseNotes @@ -0,0 +1,57 @@ +Cryptsetup 1.6.4 Release Notes +============================== + +Changes since version 1.6.3 + +* Implement new erase (with alias luksErase) command. + + The erase cryptsetup command can be used to permanently erase + all keyslots and make the LUKS container inaccessible. + (The only way to unlock such device is to use LUKS header backup + created before erase command was used.) + + You do not need to provide any password for this operation. + + This operation is irreversible. + +* Add internal "whirlpool_gcryptbug hash" for accessing flawed + Whirlpool hash in gcrypt (requires gcrypt 1.6.1 or above). + + The gcrypt version of Whirlpool hash algorithm was flawed in some + situations. + + This means that if you used Whirlpool in LUKS header and upgraded + to new gcrypt library your LUKS container become inaccessible. + + Please refer to cryptsetup FAQ for detail how to fix this situation. + +* Allow one to use --disable-gcrypt-pbkdf2 during configuration + to force use internal PBKDF2 code. + +* Require gcrypt 1.6.1 for imported implementation of PBKDF2 + (PBKDF2 in gcrypt 1.6.0 is too slow). + +* Add --keep-key to cryptsetup-reencrypt. + + This allows change of LUKS header hash (and iteration count) without + the need to reencrypt the whole data area. + (Reencryption of LUKS header only without master key change.) + +* By default verify new passphrase in luksChangeKey and luksAddKey + commands (if input is from terminal). + +* Fix memory leak in Nettle crypto backend. + +* Support --tries option even for TCRYPT devices in cryptsetup. + +* Support --allow-discards option even for TCRYPT devices. + (Note that this could destroy hidden volume and it is not suggested + by original TrueCrypt security model.) + +* Link against -lrt for clock_gettime to fix undefined reference + to clock_gettime error (introduced in 1.6.2). + +* Fix misleading error message when some algorithms are not available. + +* Count system time in PBKDF2 benchmark if kernel returns no self usage info. + (Workaround to broken getrusage() syscall with some hypervisors.) diff --git a/docs/v1.6.5-ReleaseNotes b/docs/v1.6.5-ReleaseNotes new file mode 100644 index 0000000..0f46964 --- /dev/null +++ b/docs/v1.6.5-ReleaseNotes @@ -0,0 +1,54 @@ +Cryptsetup 1.6.5 Release Notes +============================== + +Changes since version 1.6.4 + +* Allow LUKS header operation handling without requiring root privilege. + It means that you can manipulate with keyslots as a regular user, only + write access to device (or image) is required. + + This requires kernel crypto wrapper (similar to TrueCrypt device handling) + to be available (CRYPTO_USER_API_SKCIPHER kernel option). + If this kernel interface is not available, code fallbacks to old temporary + keyslot device creation (where root privilege is required). + + Note that activation, deactivation, resize and suspend operations still + need root privilege (limitation of kernel device-mapper backend). + +* Fix internal PBKDF2 key derivation function implementation for alternative + crypto backends (kernel, NSS) which do not support PBKDF2 directly and have + issues with longer HMAC keys. + + This fixes the problem for long keyfiles where either calculation is too slow + (because of internal rehashing in every iteration) or there is a limit + (kernel backend seems to not support HMAC key longer than 20480 bytes). + + (Note that for recent version of gcrypt, nettle or openssl the internal + PBKDF2 code is not compiled in and crypto library internal functions are + used instead.) + +* Support for Python3 for simple Python binding. + Python >= 2.6 is now required. You can set Python compiled version by setting + --with-python_version configure option (together with --enable-python). + +* Use internal PBKDF2 in Nettle library for Nettle crypto backend. + Cryptsetup compilation requires Nettle >= 2.6 (if using Nettle crypto backend). + +* Allow simple status of crypt device without providing metadata header. + The command "cryptsetup status" will print basic info, even if you + do not provide detached header argument. + +* Allow one to specify ECB mode in cryptsetup benchmark. + +* Add some LUKS images for regression testing. + Note that if image with Whirlpool fails, the most probable cause is that + you have old gcrypt library with flawed whirlpool hash. + Read FAQ section 8.3 for more info. + +Cryptsetup API NOTE: +The direct terminal handling for passphrase entry will be removed from +libcryptsetup in next major version (application should handle it itself). + +It means that you have to always either provide password in buffer or set +your own password callback function trhough crypt_set_password_callback(). +See API documentation (or libcryptsetup.h) for more info. diff --git a/docs/v1.6.6-ReleaseNotes b/docs/v1.6.6-ReleaseNotes new file mode 100644 index 0000000..9d1fbee --- /dev/null +++ b/docs/v1.6.6-ReleaseNotes @@ -0,0 +1,29 @@ +Cryptsetup 1.6.6 Release Notes +============================== + +Changes since version 1.6.5 + +* LUKS: Fix keyslot device access for devices which + do not support direct IO operations. (Regression in 1.6.5.) + +* LUKS: Fallback to old temporary keyslot device mapping method + if hash (for ESSIV) is not supported by userspace crypto + library. (Regression in 1.6.5.) + +* Properly activate device with discard (TRIM for SSDs) + if requested even if dm_crypt module is not yet loaded. + Only if discard is not supported by the old kernel then + the discard option is ignored. + +* Fix some static analysis build warnings (scan-build). + +* Report crypto lib version only once (and always add kernel + version) in debug output. + +Cryptsetup API NOTE: +The direct terminal handling for passphrase entry will be removed from +libcryptsetup in next major version (application should handle it itself). + +It means that you have to always either provide password in buffer or set +your own password callback function through crypt_set_password_callback(). +See API documentation (or libcryptsetup.h) for more info. diff --git a/docs/v1.6.7-ReleaseNotes b/docs/v1.6.7-ReleaseNotes new file mode 100644 index 0000000..bb7c671 --- /dev/null +++ b/docs/v1.6.7-ReleaseNotes @@ -0,0 +1,84 @@ +Cryptsetup 1.6.7 Release Notes +============================== + +Changes since version 1.6.6 + +* Cryptsetup git and wiki are now hosted on GitLab. + https://gitlab.com/cryptsetup/cryptsetup + + Repository of stable releases remains on kernel.org site + https://www.kernel.org/pub/linux/utils/cryptsetup/ + + For more info please see README file. + +* Cryptsetup TCRYPT mode now supports VeraCrypt devices (TrueCrypt extension). + + The VeraCrypt extension only increases iteration count for the key + derivation function (on-disk format is the same as TrueCrypt format). + + Note that unlocking of a VeraCrypt device can take very long time if used + on slow machines. + + To use this extension, add --veracrypt option, for example + cryptsetup open --type tcrypt --veracrypt + + For use through libcryptsetup, just add CRYPT_TCRYPT_VERA_MODES flag. + +* Support keyfile-offset and keyfile-size options even for plain volumes. + +* Support keyfile option for luksAddKey if the master key is specified. + +* For historic reasons, hashing in the plain mode is not used + if keyfile is specified (with exception of --key-file=-). + Print a warning if these parameters are ignored. + +* Support permanent device decryption for cryptsetup-reencrypt. + To remove LUKS encryption from a device, you can now use --decrypt option. + +* Allow one to use --header option in all LUKS commands. + The --header always takes precedence over positional device argument. + +* Allow luksSuspend without need to specify a detached header. + +* Detect if O_DIRECT is usable on a device allocation. + There are some strange storage stack configurations which wrongly allows + one to open devices with direct-io but fails on all IO operations later. + + Cryptsetup now tries to read the device first sector to ensure it can use + direct-io. + +* Add low-level performance options tuning for dmcrypt (for Linux 4.0 and later). + + Linux kernel 4.0 contains rewritten dmcrypt code which tries to better utilize + encryption on parallel CPU cores. + + While tests show that this change increases performance on most configurations, + dmcrypt now provides some switches to change its new behavior. + + You can use them (per-device) with these cryptsetup switches: + --perf-same_cpu_crypt + --perf-submit_from_crypt_cpus + + Please use these only in the case of serious performance problems. + Refer to the cryptsetup man page and dm-crypt documentation + (for same_cpu_crypt and submit_from_crypt_cpus options). + https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt + +* Get rid of libfipscheck library. + (Note that this option was used only for Red Hat and derived distributions.) + With recent FIPS changes we do not need to link to this FIPS monster anymore. + Also drop some no longer needed FIPS mode checks. + +* Many fixes and clarifications to man pages. + +* Prevent compiler to optimize-out zeroing of buffers for on-stack variables. + +* Fix a crash if non-GNU strerror_r is used. + +Cryptsetup API NOTE: +The direct terminal handling for passphrase entry will be removed from +libcryptsetup in next major version (application should handle it itself). + +It means that you have to always either provide password in buffer or set +your own password callback function through crypt_set_password_callback(). +See API documentation (or libcryptsetup.h) for more info. diff --git a/docs/v1.6.8-ReleaseNotes b/docs/v1.6.8-ReleaseNotes new file mode 100644 index 0000000..8ae0da9 --- /dev/null +++ b/docs/v1.6.8-ReleaseNotes @@ -0,0 +1,47 @@ +Cryptsetup 1.6.8 Release Notes +============================== + +Changes since version 1.6.7 + +* If the null cipher (no encryption) is used, allow only empty password for LUKS. + (Previously cryptsetup accepted any password in this case.) + + The null cipher can be used only for testing and it is used temporarily during + offline encrypting not yet encrypted device (cryptsetup-reencrypt tool). + + Accepting only empty password prevents situation when someone adds another + LUKS device using the same UUID (UUID of existing LUKS device) with faked + header containing null cipher. + This could force user to use different LUKS device (with no encryption) + without noticing. + (IOW it prevents situation when attacker intentionally forces + user to boot into different system just by LUKS header manipulation.) + + Properly configured systems should have an additional integrity protection + in place here (LUKS here provides only confidentiality) but it is better + to not allow this situation in the first place. + + (For more info see QubesOS Security Bulletin QSB-019-2015.) + +* Properly support stdin "-" handling for luksAddKey for both new and old + keyfile parameters. + +* If encrypted device is file-backed (it uses underlying loop device), + cryptsetup resize will try to resize underlying loop device as well. + (It can be used to grow up file-backed device in one step.) + +* Cryptsetup now allows one to use empty password through stdin pipe. + (Intended only for testing in scripts.) + +Cryptsetup API NOTE: + +Direct terminal handling and password calling callback for passphrase +entry will be removed from libcryptsetup in next major (2.x) version +(application should handle it itself). +It means that application have to always provide password in API calls. + +Functions returning last error will be removed in next major version (2.x). +These functions did not work properly for early initialization errors +and application can implement better function easily using own error callback. + +See comments in libcryptsetup.h for more info about deprecated functions. diff --git a/docs/v1.7.0-ReleaseNotes b/docs/v1.7.0-ReleaseNotes new file mode 100644 index 0000000..cd568c1 --- /dev/null +++ b/docs/v1.7.0-ReleaseNotes @@ -0,0 +1,81 @@ +Cryptsetup 1.7.0 Release Notes +============================== + +The cryptsetup 1.7 release changes defaults for LUKS, +there are no API changes. + +Changes since version 1.6.8 + +* Default hash function is now SHA256 (used in key derivation function + and anti-forensic splitter). + + Note that replacing SHA1 with SHA256 is not for security reasons. + (LUKS does not have problems even if collisions are found for SHA1, + for details see FAQ item 5.20). + + Using SHA256 as default is mainly to prevent compatibility problems + on hardened systems where SHA1 is already be phased out. + + Note that all checks (kernel crypto API availability check) now uses + SHA256 as well. + +* Default iteration time for PBKDF2 is now 2 seconds. + + Increasing iteration time is in combination with PBKDF2 benchmark + fixes a try to keep PBKDF2 iteration count still high enough and + also still acceptable for users. + + N.B. Long term is to replace PBKDF2 algorithm with Password Hashing + Competition winner - Argon2. + + Distributions can still change these defaults in compilation time. + + You can change iteration time and used hash function in existing LUKS + header with cryptsetup-reencrypt utility even without full reencryption + of device (see --keep-key option). + +* Fix PBKDF2 iteration benchmark for longer key sizes. + + The previous PBKDF2 benchmark code did not take into account + output key length properly. + + For SHA1 (with 160-bits output) and 256-bit keys (and longer) + it means that the final iteration value was higher than it should be. + + For other hash algorithms (like SHA256 or SHA512) it caused + that iteration count was lower (in comparison to SHA1) than + expected for the requested time period. + + The PBKDF2 benchmark code is now fixed to use the key size for + the formatted device (or default LUKS key size if running in informational + benchmark mode). + + Thanks to A.Visconti, S.Bossi, A.Calo and H.Ragab + (http://www.club.di.unimi.it/) for point this out. + (Based on "What users should know about Full Disk Encryption + based on LUKS" paper to be presented on CANS2015). + +* Remove experimental warning for reencrypt tool. + The strong request for full backup before using reencryption utility + still applies :) + +* Add optional libpasswdqc support for new LUKS passwords. + + If password is entered through terminal (no keyfile specified) and + cryptsetup is compiled with --enable-passwdqc[=/etc/passwdqc.conf], + configured system passwdqc settings are used to check password quality. + +* Update FAQ document. + +Cryptsetup API NOTE: + +Direct terminal handling and password calling callback for passphrase +entry will be removed from libcryptsetup in next major (2.x) version +(application should handle it itself). +It means that application have to always provide password in API calls. + +Functions returning last error will be removed in next major version (2.x). +These functions did not work properly for early initialization errors +and application can implement better function easily using own error callback. + +See comments in libcryptsetup.h for more info about deprecated functions. diff --git a/docs/v1.7.1-ReleaseNotes b/docs/v1.7.1-ReleaseNotes new file mode 100644 index 0000000..057c135 --- /dev/null +++ b/docs/v1.7.1-ReleaseNotes @@ -0,0 +1,36 @@ +Cryptsetup 1.7.1 Release Notes +============================== + +Changes since version 1.7.0 + +* Code now uses kernel crypto API backend according to new + changes introduced in mainline kernel + + While mainline kernel should contain backward compatible + changes, some stable series kernels do not contain fully + backported compatibility patches. + Without these patches most of cryptsetup operations + (like unlocking device) fail. + + This change in cryptsetup ensures that all operations using + kernel crypto API works even on these kernels. + +* The cryptsetup-reencrypt utility now properly detects removal + of underlying link to block device and does not remove + ongoing re-encryption log. + This allows proper recovery (resume) of reencrypt operation later. + + NOTE: Never use /dev/disk/by-uuid/ path for reencryption utility, + this link disappears once the device metadata is temporarily + removed from device. + +* Cryptsetup now allows special "-" (standard input) keyfile handling + even for TCRYPT (TrueCrypt and VeraCrypt compatible) devices. + +* Cryptsetup now fails if there are more keyfiles specified + for non-TCRYPT device. + +* The luksKillSlot command now does not suppress provided password + in batch mode (if password is wrong slot is not destroyed). + Note that not providing password in batch mode means that keyslot + is destroyed unconditionally. diff --git a/docs/v1.7.2-ReleaseNotes b/docs/v1.7.2-ReleaseNotes new file mode 100644 index 0000000..6323430 --- /dev/null +++ b/docs/v1.7.2-ReleaseNotes @@ -0,0 +1,37 @@ +Cryptsetup 1.7.2 Release Notes +============================== + +Changes since version 1.7.1 + +* Update LUKS documentation format. + Clarify fixed sector size and keyslots alignment. + +* Support activation options for error handling modes in Linux kernel + dm-verity module: + + --ignore-corruption - dm-verity just logs detected corruption + + --restart-on-corruption - dm-verity restarts the kernel if corruption is detected + + If the options above are not specified, default behavior for dm-verity remains. + Default is that I/O operation fails with I/O error if corrupted block is detected. + + --ignore-zero-blocks - Instructs dm-verity to not verify blocks that are expected + to contain zeroes and always return zeroes directly instead. + + NOTE that these options could have security or functional impacts, + do not use them without assessing the risks! + +* Fix help text for cipher benchmark specification (mention --cipher option). + +* Fix off-by-one error in maximum keyfile size. + Allow keyfiles up to compiled-in default and not that value minus one. + +* Support resume of interrupted decryption in cryptsetup-reencrypt utility. + To resume decryption, LUKS device UUID (--uuid option) option must be used. + +* Do not use direct-io for LUKS header with unaligned keyslots. + Such headers were used only by the first cryptsetup-luks-1.0.0 release (2005). + +* Fix device block size detection to properly work on particular file-based + containers over underlying devices with 4k sectors. diff --git a/docs/v1.7.3-ReleaseNotes b/docs/v1.7.3-ReleaseNotes new file mode 100644 index 0000000..4a2757c --- /dev/null +++ b/docs/v1.7.3-ReleaseNotes @@ -0,0 +1,20 @@ +Cryptsetup 1.7.3 Release Notes +============================== + +Changes since version 1.7.2 + +* Fix device access to hash offsets located beyond the 2GB device boundary in veritysetup. + +* Set configured (compile-time) default iteration time for devices created directly through + libcryptsetup (default was hardcoded 1 second, the configured value applied only + for cryptsetup application). + +* Fix PBKDF2 benchmark to not double iteration count for specific corner case. + If the measurement function returns exactly 500 ms, the iteration calculation loop + doubled iteration count but instead of repeating measurement it used this value directly. + +* OpenSSL backend: fix memory leak if hash context was repeatedly reused. + +* OpenSSL backend: add support for OpenSSL 1.1.0. + +* Fix several minor spelling errors. diff --git a/docs/v1.7.4-ReleaseNotes b/docs/v1.7.4-ReleaseNotes new file mode 100644 index 0000000..2b24754 --- /dev/null +++ b/docs/v1.7.4-ReleaseNotes @@ -0,0 +1,22 @@ +Cryptsetup 1.7.4 Release Notes +============================== + +Changes since version 1.7.3 + +* Allow one to specify LUKS1 hash algorithm in Python luksFormat wrapper. + +* Use LUKS1 compiled-in defaults also in Python wrapper. + +* OpenSSL backend: Fix OpenSSL 1.1.0 support without backward compatible API. + +* OpenSSL backend: Fix LibreSSL compatibility. + +* Check for data device and hash device area overlap in veritysetup. + +* Fix a possible race while allocating a free loop device. + +* Fix possible file descriptor leaks if libcryptsetup is run from a forked process. + +* Fix missing same_cpu_crypt flag in status command. + +* Various updates to FAQ and man pages. diff --git a/docs/v1.7.5-ReleaseNotes b/docs/v1.7.5-ReleaseNotes new file mode 100644 index 0000000..eec4315 --- /dev/null +++ b/docs/v1.7.5-ReleaseNotes @@ -0,0 +1,22 @@ +Cryptsetup 1.7.5 Release Notes +============================== + +Changes since version 1.7.4 + +* Fixes to luksFormat to properly support recent kernel running in FIPS mode. + + Cryptsetup must never use a weak key even if it is just used for testing + of algorithm availability. In FIPS mode, weak keys are always rejected. + + A weak key is for example detected if the XTS encryption mode use + the same key for the tweak and the encryption part. + +* Fixes accesses to unaligned hidden legacy TrueCrypt header. + + On a native 4k-sector device the old hidden TrueCrypt header is not + aligned with the hw sector size (this problem was fixed in later TrueCrypt + on-disk format versions). + + Cryptsetup now properly aligns the read so it does not fail. + +* Fixes to optional dracut ramdisk scripts for offline re-encryption on initial boot. diff --git a/docs/v2.0.0-ReleaseNotes b/docs/v2.0.0-ReleaseNotes new file mode 100644 index 0000000..401484d --- /dev/null +++ b/docs/v2.0.0-ReleaseNotes @@ -0,0 +1,605 @@ +Cryptsetup 2.0.0 Release Notes +============================== +Stable release with experimental features. + +This version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +NOTE: This version changes soname of libcryptsetup library and increases +major version for all public symbols. +Most of the old functions are fully backward compatible, so only +recompilation of programs should be needed. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +To provide all security features of authenticated encryption we need +better nonce-reuse resistant algorithm in kernel (see note below). +For now, please use authenticated encryption as experimental feature. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.0-RC1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Limit KDF requested (for format) memory by available physical memory. + On some systems too high requested amount of memory causes OOM killer + to kill the process (instead of returning ENOMEM). + We never try to use more than half of available physical memory. + +* Ignore device alignment if it is not multiple of minimal-io. + Some USB enclosures seems to report bogus topology info that + prevents to use LUKS detached header. + +Changes since version 2.0.0-RC0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Enable to use system libargon2 instead of bundled version. + Renames --disable-argon2 to --disable-internal-argon2 option + and adds --enable-libargon2 flag to allow system libargon2. + +* Changes in build system (Automake) + - The build system now uses non-recursive automake (except for tests). + (Tools binaries are now located in buildroot directory.) + - New --disable-cryptsetup option to disable build of cryptsetup tool. + - Enable build of cryptsetup-reencrypt by default. + +* Install tmpfiles.d configuration for LUKS2 locking directory. + You can overwrite this using --with-tmpfilesdir configure option. + If your distro does not support tmpfiles.d directory, you have + to create locking directory (/run/lock/cryptsetup) in cryptsetup + package (or init scripts). + +* Adds limited support for offline reencryption of LUKS2 format. + +* Decrease size of testing images (and the whole release archive). + +* Fixes for several memory leaks found by Valgrind and Coverity tools. + +* Fixes for several typos in man pages and error messages. + +* LUKS header file in luksFormat is now automatically created + if it does not exist. + +* Do not allow resize if device size is not aligned to sector size. + +Cryptsetup 2.0.0 RC0 Release Notes +================================== + +Important features +~~~~~~~~~~~~~~~~~~ + +* New command integritysetup: support for the new dm-integrity kernel target. + + The dm-integrity is a new kernel device-mapper target that introduces + software emulation of per-sector integrity fields on the disk sector level. + It is available since Linux kernel version 4.12. + + The provided per-sector metadata fields can be used for storing a data + integrity checksum (for example CRC32). + The dm-integrity implements data journal that enforces atomic update + of a sector and its integrity metadata. + + Integritysetup is a CLI utility that can setup standalone dm-integrity + devices (that internally check integrity of data). + + Integritysetup is intended to be used for settings that require + non-cryptographic data integrity protection with no data encryption. + For setting integrity protected encrypted devices, see disk authenticated + encryption below. + + Note that after formatting the checksums need to be initialized; + otherwise device reads will fail because of integrity errors. + Integritysetup by default tries to wipe the device with zero blocks + to avoid this problem. Device wipe can be time-consuming, you can skip + this step by specifying --no-wipe option. + (But note that not wiping device can cause some operations to fail + if a write is not multiple of page size and kernel page cache tries + to read sectors with not yet initialized checksums.) + + The default setting is tag size 4 bytes per-sector and CRC32C protection. + To format device with these defaults: + $ integritysetup format + $ integritysetup open + + Note that used algorithm (unlike tag size) is NOT stored in device + kernel superblock and if you use different algorithm, you MUST specify + it in every open command, for example: + $ integritysetup format --tag-size 32 --integrity sha256 + $ integritysetup open --integrity sha256 + + For more info, see integrity man page. + +* Veritysetup command can now format and activate dm-verity devices + that contain Forward Error Correction (FEC) (Reed-Solomon code is used). + This feature is used on most of Android devices already (available since + Linux kernel 4.5). + + There are new options --fec-device, --fec-offset to specify data area + with correction code and --fec-roots that set Redd-Solomon generator roots. + This setting can be used for format command (veritysetup will calculate + and store RS codes) or open command (veritysetup configures kernel + dm-verity to use RS codes). + + For more info see veritysetup man page. + +* Support for larger sector sizes for crypt devices. + + LUKS2 and plain crypt devices can be now configured with larger encryption + sector (typically 4096 bytes, sector size must be the power of two, + maximal sector size is 4096 bytes for portability). + Large sector size can decrease encryption overhead and can also help + with some specific crypto hardware accelerators that perform very + badly with 512 bytes sectors. + + Note that if you configure such a larger sector of the device that does use + smaller physical sector, there is a possibility of a data corruption during + power fail (partial sector writes). + + WARNING: If you use different sector size for a plain device after data were + stored, the decryption will produce garbage. + + For LUKS2, the sector size is stored in metadata and cannot be changed later. + +LUKS2 format and features +~~~~~~~~~~~~~~~~~~~~~~~~~ +The LUKS2 is an on-disk storage format designed to provide simple key +management, primarily intended for Full Disk Encryption based on dm-crypt. + +The LUKS2 is inspired by LUKS1 format and in some specific situations (most +of the default configurations) can be converted in-place from LUKS1. + +The LUKS2 format is designed to allow future updates of various +parts without the need to modify binary structures and internally +uses JSON text format for metadata. Compilation now requires the json-c library +that is used for JSON data processing. + +On-disk format provides redundancy of metadata, detection +of metadata corruption and automatic repair from metadata copy. + +NOTE: For security reasons, there is no redundancy in keyslots binary data +(encrypted keys) but the format allows adding such a feature in future. + +NOTE: to operate correctly, LUKS2 requires locking of metadata. +Locking is performed by using flock() system call for images in file +and for block device by using a specific lock file in /run/lock/cryptsetup. + +This directory must be created by distribution (do not rely on internal +fallback). For systemd-based distribution, you can simply install +scripts/cryptsetup.conf into tmpfiles.d directory. + +For more details see LUKS2-format.txt and LUKS2-locking.txt in the docs +directory. (Please note this is just overview, there will be more formal +documentation later.) + +LUKS2 use +~~~~~~~~~ + +LUKS2 allows using all possible configurations as LUKS1. + +To format device as LUKS2, you have to add "--type luks2" during format: + + $ cryptsetup luksFormat --type luks2 + +All commands issued later will recognize the new format automatically. + +The newly added features in LUKS2 include: + +* Authenticated disk (sector) encryption (EXPERIMENTAL) + + Legacy Full disk encryption (FDE), for example, LUKS1, is a length-preserving + encryption (plaintext is the same size as a ciphertext). + Such FDE can provide data confidentiality, but cannot provide sound data + integrity protection. + + Full disk authenticated encryption is a way how to provide both + confidentiality and data integrity protection. Integrity protection here means + not only detection of random data corruption (silent data corruption) but also + prevention of an unauthorized intentional change of disk sector content. + + NOTE: Integrity protection of this type cannot prevent a replay attack. + An attacker can replace the device or its part of the old content, and it + cannot be detected. + If you need such protection, better use integrity protection on a higher layer. + + For data integrity protection on the sector level, we need additional + per-sector metadata space. In LUKS2 this space is provided by a new + device-mapper dm-integrity target (available since kernel 4.12). + Here the integrity target provides only reliable per-sector metadata store, + and the whole authenticated encryption is performed inside dm-crypt stacked + over the dm-integrity device. + + For encryption, Authenticated Encryption with Additional Data (AEAD) is used. + Every sector is processed as a encryption request of this format: + + |----- AAD -------|------ DATA -------|-- AUTH TAG --| + | (authenticated) | (auth+encryption) | | + | sector_LE | IV | sector in/out | tag in/out | + + AEAD encrypts the whole sector and also authenticates sector number + (to detect sector relocation) and also authenticates Initialization Vector. + + AEAD encryption produces encrypted data and authentication tag. + The authenticated tag is then stored in per-sector metadata space provided + by dm-integrity. + + Most of the current AEAD algorithms requires IV as a nonce, value that is + never reused. Because sector number, as an IV, cannot be used in this + environment, we use a new random IV (IV is a random value generated by system + RNG on every write). This random IV is then stored in the per-sector metadata + as well. + + Because the authentication tag (and IV) requires additional space, the device + provided for a user has less capacity. Also, the data journalling means that + writes are performed twice, decreasing throughput. + + This integrity protection works better with SSDs. If you want to ignore + dm-integrity data journal (because journalling is performed on some higher + layer or you just want to trade-off performance to safe recovery), you can + switch journal off with --integrity-no-journal option. + (This flag can be stored persistently as well.) + + Note that (similar to integritysetup) the device read will fail if + authentication tag is not initialized (no previous write). + By default cryptsetup run wipe of a device (writing zeroes) to initialize + authentication tags. This operation can be very time-consuming. + You can skip device wipe using --integrity-no-wipe option. + + To format LUKS2 device with integrity protection, use new --integrity option. + + For now, there are very few AEAD algorithms that can be used, and some + of them are known to be problematic. In this release we support only + a few of AEAD algorithms (options are for now hard coded), later this + extension will be completely algorithm-agnostic. + + For testing of authenticated encryption, these algorithms work for now: + + 1) aes-xts-plain64 with hmac-sha256 or hmac-sha512 as the authentication tag. + (Common FDE mode + independent authentication tag. Authentication key + for HMAC is independently generated. This mode is very slow.) + $ cryptsetup luksFormat --type luks2 --cipher aes-xts-plain64 --integrity hmac-sha256 + + 2) aes-gcm-random (native AEAD mode) + DO NOT USE in production! The GCM mode uses only 96-bit nonce, + and possible collision means fatal security problem. + GCM mode has very good hardware support through AES-NI, so it is useful + for performance testing. + $ cryptsetup luksFormat --type luks2 --cipher aes-gcm-random --integrity aead + + 3) ChaCha20 with Poly1305 authenticator (according to RFC7539) + $ cryptsetup luksFormat --type luks2 --cipher chacha20-random --integrity poly1305 + + To specify AES128/AES256 just specify proper key size (without possible + authentication key). Other symmetric ciphers, like Serpent or Twofish, + should work as well. The mode 1) and 2) should be compatible with IEEE 1619.1 + standard recommendation. + + There will be better suitable authenticated modes available soon + For now we are just preparing framework to enable it (and hopefully improve security of FDE). + + FDE authenticated encryption is not a replacement for filesystem layer + authenticated encryption. The goal is to provide at least something because + data integrity protection is often completely ignored in today systems. + +* New memory-hard PBKDF + + LUKS1 introduced Password-Based Key Derivation Function v2 as a tool to + increase attacker cost for a dictionary and brute force attacks. + The PBKDF2 uses iteration count to increase time of key derivation. + Unfortunately, with modern GPUs, the PBKDF2 calculations can be run + in parallel and PBKDF2 can no longer provide the best available protection. + Increasing iteration count just cannot prevent massive parallel dictionary + password attacks in long-term. + + To solve this problem, a new PBKDF, based on so-called memory-hard functions + can be used. Key derivation with memory-hard function requires a certain + amount of memory to compute its output. The memory requirement is very + costly for GPUs and prevents these systems to operate effectively, + increasing cost for attackers. + + LUKS2 introduces support for Argon2i and Argon2id as a PBKDF. + Argon2 is the winner of Password Hashing Competition and is currently + in final RFC draft specification. + + For now, libcryptsetup contains the embedded copy of reference implementation + of Argon2 (that is easily portable to all architectures). + Later, once this function is available in common crypto libraries, it will + switch to external implementation. (This happened for LUKS1 and PBKDF2 + as well years ago.) + With using reference implementation (that is not optimized for speed), there + is some performance penalty. However, using memory-hard PBKDF should still + significantly complicate GPU-optimized dictionary and brute force attacks. + + The Argon2 uses three costs: memory, time (number of iterations) and parallel + (number of threads). + Note that time and memory cost highly influences each other (accessing a lot + of memory takes more time). + + There is a new benchmark that tries to calculate costs to take similar way as + in LUKS1 (where iteration is measured to take 1-2 seconds on user system). + Because now there are more cost variables, it prefers time cost (iterations) + and tries to find required memory that fits. (IOW required memory cost can be + lower if the benchmarks are not able to find required parameters.) + The benchmark cannot run too long, so it tries to approximate next step + for benchmarking. + + For now, default LUKS2 PBKDF algorithm is Argon2i (data independent variant) + with memory cost set to 128MB, time to 800ms and parallel thread according + to available CPU cores but no more than 4. + + All default parameters can be set during compile time and also set on + the command line by using --pbkdf, --pbkdf-memory, --pbkdf-parallel and + --iter-time options. + (Or without benchmark directly by using --pbkdf-force-iterations, see below.) + + You can still use PBKDF2 even for LUKS2 by specifying --pbkdf pbkdf2 option. + (Then only iteration count is applied.) + +* Use of kernel keyring + + Kernel keyring is a storage for sensitive material (like cryptographic keys) + inside Linux kernel. + + LUKS2 uses keyring for two major functions: + + - To store volume key for dm-crypt where it avoids sending volume key in + every device-mapper ioctl structure. Volume key is also no longer directly + visible in a dm-crypt mapping table. The key is not available for the user + after dm-crypt configuration (obviously except direct memory scan). + Use of kernel keyring can be disabled in runtime by --disable-keyring option. + + - As a tool to automatically unlock LUKS device if a passphrase is put into + kernel keyring and proper keyring token is configured. + + This allows storing a secret (passphrase) to kernel per-user keyring by + some external tool (for example some TPM handler) and LUKS2, if configured, + will automatically search in the keyring and unlock the system. + For more info see Tokens section below. + +* Persistent flags + The activation flags (like allow-discards) can be stored in metadata and used + automatically by all later activations (even without using crypttab). + + To store activation flags permanently, use activation command with required + flags and add --persistent option. + + For example, to mark device to always activate with TRIM enabled, + use (for LUKS2 type): + + $ cryptsetup open --allow-discards --persistent + + You can check persistent flags in dump command output: + + $ cryptsetup luksDump + +* Tokens and auto-activation + + A LUKS2 token is an object that can be described "how to get passphrase or key" + to unlock particular keyslot. + (Also it can be used to store any additional metadata, and with + the libcryptsetup interface it can be used to define user token types.) + + Cryptsetup internally implements keyring token. Cryptsetup tries to use + available tokens before asking for the passphrase. For keyring token, + it means that if the passphrase is available under specified identifier + inside kernel keyring, the device is automatically activated using this + stored passphrase. + + Example of using LUKS2 keyring token: + + # Adding token to metadata with "my_token" identifier (by default it applies to all keyslots). + $ cryptsetup token add --key-description "my_token" + + # Storing passphrase to user keyring (this can be done by an external application) + $ echo -n | keyctl padd user my_token @u + + # Now cryptsetup activates automatically if it finds correct passphrase + $ cryptsetup open + + The main reason to use tokens this way is to separate possible hardware + handlers from cryptsetup code. + +* Keyslot priorities + + LUKS2 keyslot can have a new priority attribute. + The default is "normal". The "prefer" priority tell the keyslot to be tried + before other keyslots. Priority "ignore" means that keyslot will never be + used if not specified explicitly (it can be used for backup administrator + passwords that are used only situations when a user forgets own passphrase). + + The priority of keyslot can be set with new config command, for example + $ cryptsetup config --key-slot 1 --priority prefer + + Setting priority to normal will reset slot to normal state. + +* LUKS2 label and subsystem + + The header now contains additional fields for label and subsystem (additional + label). These fields can be used similar to filesystem label and will be + visible in udev rules to possible filtering. (Note that blkid do not yet + contain the LUKS scanning code). + + By default both labels are empty. Label and subsystem are always set together + (no option means clear the label) with the config command: + + $ cryptsetup config --label my_device --subsystem "" + +* In-place conversion form LUKS1 + + To allow easy testing and transition to the new LUKS2 format, there is a new + convert command that allows in-place conversion from the LUKS1 format and, + if there are no incompatible options, also conversion back from LUKS2 + to LUKS1 format. + + Note this command can be used only on some LUKS1 devices (some device header + sizes are not supported). + This command is dangerous, never run it without header backup! + If something fails in the middle of conversion (IO error), the header + is destroyed. (Note that conversion requires move of keyslot data area to + a different offset.) + + To convert header in-place to LUKS2 format, use + $ cryptsetup convert --type luks2 + + To convert it back to LUKS1 format, use + $ cryptsetup convert --type luks1 + + You can verify LUKS version with luksDump command. + $ cryptsetup luksDump + + Note that some LUKS2 features will make header incompatible with LUKS1 and + conversion will be rejected (for example using new Argon2 PBKDF or integrity + extensions). Some minor attributes can be lost in conversion. + +Other changes +~~~~~~~~~~~~~ + +* Explicit KDF iterations count setting + + With new PBKDF interface, there is also the possibility to setup PBKDF costs + directly, avoiding benchmarks. This can be useful if device is formatted to be + primarily used on a different system. + + The option --pbkdf-force-iterations is available for both LUKS1 and LUKS2 + format. Using this option can cause device to have either very low or very + high PBKDF costs. + In the first case it means bad protection to dictionary attacks, in the second + case, it can mean extremely high unlocking time or memory requirements. + Use only if you are sure what you are doing! + + Not that this setting also affects iteration count for the key digest. + For LUKS1 iteration count for digest will be approximately 1/8 of requested + value, for LUKS2 and "pbkdf2" digest minimal PBKDF2 iteration count (1000) + will be used. You cannot set lower iteration count than the internal minimum + (1000 for PBKDF2). + + To format LUKS1 device with forced iteration count (and no benchmarking), use + $ cryptsetup luksFormat --pbkdf-force-iterations 22222 + + For LUKS2 it is always better to specify full settings (do not rely on default + cost values). + For example, we can set to use Argon2id with iteration cost 5, memory 128000 + and parallel set 1: + $ cryptsetup luksFormat --type luks2 \ + --pbkdf argon2id --pbkdf-force-iterations 5 --pbkdf-memory 128000 --pbkdf-parallel 1 + +* VeraCrypt PIM + + Cryptsetup can now also open VeraCrypt device that uses Personal Iteration + Multiplier (PIM). PIM is an integer value that user must remember additionally + to passphrase and influences PBKDF2 iteration count (without it VeraCrypt uses + a fixed number of iterations). + + To open VeraCrypt device with PIM settings, use --veracrypt-pim (to specify + PIM on the command line) or --veracrypt-query-pim to query PIM interactively. + +* Support for plain64be IV + + The plain64be is big-endian variant of plain64 Initialization Vector. It is + used in some images of hardware-based disk encryption systems. Supporting this + variant allows using dm-crypt to map such images through cryptsetup. + +* Deferral removal + + Cryptsetup now can mark device for deferred removal by using a new option + --deferred. This means that close command will not fail if the device is still + in use, but will instruct the kernel to remove the device automatically after + use count drops to zero (for example, once the filesystem is unmounted). + +* A lot of updates to man pages and many minor changes that would make this + release notes too long ;-) + +Libcryptsetup API changes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +These API functions were removed, libcryptsetup no longer handles password +retries from terminal (application should handle terminal operations itself): + crypt_set_password_callback; + crypt_set_timeout; + crypt_set_password_retry; + crypt_set_password_verify; + +This call is removed (no need to keep typo backward compatibility, +the proper function is crypt_set_iteration_time :-) + crypt_set_iterarion_time; + +These calls were removed because are not safe, use per-context +error callbacks instead: + crypt_last_error; + crypt_get_error; + +The PBKDF benchmark was replaced by a new function that uses new KDF structure + crypt_benchmark_kdf; (removed) + crypt_benchmark_pbkdf; (new API call) + +These new calls are now exported, for details see libcryptsetup.h: + crypt_keyslot_add_by_key; + crypt_keyslot_set_priority; + crypt_keyslot_get_priority; + + crypt_token_json_get; + crypt_token_json_set; + crypt_token_status; + crypt_token_luks2_keyring_get; + crypt_token_luks2_keyring_set; + crypt_token_assign_keyslot; + crypt_token_unassign_keyslot; + crypt_token_register; + + crypt_activate_by_token; + crypt_activate_by_keyring; + crypt_deactivate_by_name; + + crypt_metadata_locking; + crypt_volume_key_keyring; + crypt_get_integrity_info; + crypt_get_sector_size; + crypt_persistent_flags_set; + crypt_persistent_flags_get; + crypt_set_pbkdf_type; + crypt_get_pbkdf_type; + + crypt_convert; + crypt_keyfile_read; + crypt_wipe; + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* There will be better documentation and examples. + +* There will be some more formal definition of the threat model for integrity + protection. (And a link to some papers discussing integrity protection, + once it is, hopefully, accepted and published.) + +* Offline re-encrypt tool LUKS2 support is currently limited. + There will be online LUKS2 re-encryption tool in future. + +* Authenticated encryption will use new algorithms from CAESAR competition + (https://competitions.cr.yp.to/caesar.html) once these algorithms are available + in kernel (more on this later). + NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305) + in kernel have too small 96-bit nonces that are problematic with + randomly generated IVs (the collision probability is not negligible). + For the GCM, nonce collision is a fatal problem. + +* Authenticated encryption do not set encryption for dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* Some utilities (blkid, systemd-cryptsetup) have already support for LUKS + but not yet in released version (support in crypttab etc). + +* There are some examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be deprecated soon in favor + of python bindings to libblockdev library (that can already handle LUKS1 devices). diff --git a/docs/v2.0.1-ReleaseNotes b/docs/v2.0.1-ReleaseNotes new file mode 100644 index 0000000..0cc13b9 --- /dev/null +++ b/docs/v2.0.1-ReleaseNotes @@ -0,0 +1,109 @@ +Cryptsetup 2.0.1 Release Notes +============================== +Stable and bug-fix release with experimental features. + +This version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +To provide all security features of authenticated encryption we need +a better nonce-reuse resistant algorithm in the kernel (see note below). +For now, please use authenticated encryption as an experimental feature. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* To store volume key into kernel keyring, kernel 4.15 with dm-crypt 1.18.1 + is required. If a volume key is stored in keyring (LUKS2 only), + the dm-crypt v1.15.0 through v1.18.0 contains a serious bug that may cause + data corruption for ciphers with ESSIV. + (The key for ESSIV is zeroed because of code misplacement.) + This bug is not present for LUKS1 or any other IVs used in LUKS modes. + This change is not visible to the user (except dmsetup output). + +* Increase maximum allowed PBKDF memory-cost limit to 4 GiB. + The Argon2 PBKDF uses 1GiB by default; this is also limited by the amount + of physical memory available (maximum is half of the physical memory). + +* Use /run/cryptsetup as default for cryptsetup locking dir. + There were problems with sharing /run/lock with lockdev, and in the early + boot, the directory was missing. + The directory can be changed with --with-luks2-lock-path and + --with-luks2-lock-dir-perms configure switches. + +* Introduce new 64-bit byte-offset *keyfile_device_offset functions. + + The keyfile interface was designed, well, for keyfiles. Unfortunately, + there are user cases where a keyfile can be placed on a device, and + size_t offset can overflow on 32-bit systems. + + New set of functions that allow 64-bit offsets even on 32bit systems + are now available: + + - crypt_resume_by_keyfile_device_offset + - crypt_keyslot_add_by_keyfile_device_offset + - crypt_activate_by_keyfile_device_offset + - crypt_keyfile_device_read + + The new functions have added the _device_ in name. + Old functions are just internal wrappers around these. + + Also cryptsetup --keyfile-offset and --new-keyfile-offset now allows + 64-bit offsets as parameters. + +* Add error hint for wrongly formatted cipher strings in LUKS1 and + properly fail in luksFormat if cipher format is missing required IV. + For now, crypto API quietly used cipher without IV if a cipher + algorithm without IV specification was used (e.g., aes-xts). + This caused fail later during activation. + +* Configure check for a recent Argon2 lib to support mandatory Argon2id. + +* Fix for the cryptsetup-reencrypt static build if pwquality is enabled. + +* Update LUKS1 standard doc (https links in the bibliography). + + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* There will be better documentation and examples. + +* There will be some more formal definition of the threat model for integrity + protection. (And a link to some papers discussing integrity protection, + once it is, hopefully, accepted and published.) + +* Offline re-encrypt tool LUKS2 support is currently limited. + There will be online LUKS2 re-encryption tool in future. + +* Authenticated encryption will use new algorithms from CAESAR competition + (https://competitions.cr.yp.to/caesar.html) once these algorithms are + available in the kernel (more on this later). + NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305) + in the kernel have too small 96-bit nonces that are problematic with + randomly generated IVs (the collision probability is not negligible). + For the GCM, nonce collision is a fatal problem. + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be deprecated soon in favor + of python bindings to the libblockdev library (that can already handle LUKS1 + devices). diff --git a/docs/v2.0.2-ReleaseNotes b/docs/v2.0.2-ReleaseNotes new file mode 100644 index 0000000..bda57fd --- /dev/null +++ b/docs/v2.0.2-ReleaseNotes @@ -0,0 +1,93 @@ +Cryptsetup 2.0.2 Release Notes +============================== +Stable and bug-fix release with experimental features. + +Cryptsetup 2.x version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +To provide all security features of authenticated encryption, we need +a better nonce-reuse resistant algorithm in the kernel (see note below). +For now, please use authenticated encryption as an experimental feature. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix a regression in early detection of inactive keyslot for luksKillSlot. + It tried to ask for passphrase even for already erased keyslot. + +* Fix a regression in loopaesOpen processing for keyfile on standard input. + Use of "-" argument was not working properly. + +* Add LUKS2 specific options for cryptsetup-reencrypt. + Tokens and persistent flags are now transferred during reencryption; + change of PBKDF keyslot parameters is now supported and allows one + to set precalculated values (no benchmarks). + +* Do not allow LUKS2 --persistent and --test-passphrase cryptsetup flags + combination. Persistent flags are now stored only if the device was + successfully activated with the specified flags. + +* Fix integritysetup format after recent Linux kernel changes that + requires to setup key for HMAC in all cases. + Previously integritysetup allowed HMAC with zero key that behaves + like a plain hash. + +* Fix VeraCrypt PIM handling that modified internal iteration counts + even for subsequent activations. The PIM count is no longer printed + in debug log as it is sensitive information. + Also, the code now skips legacy TrueCrypt algorithms if a PIM + is specified (they cannot be used with PIM anyway). + +* PBKDF values cannot be set (even with force parameters) below + hardcoded minimums. For PBKDF2 is it 1000 iterations, for Argon2 + it is 4 iterations and 32 KiB of memory cost. + +* Introduce new crypt_token_is_assigned() API function for reporting + the binding between token and keyslots. + +* Allow crypt_token_json_set() API function to create internal token types. + Do not allow unknown fields in internal token objects. + +* Print message in cryptsetup that about was aborted if a user did not + answer YES in a query. + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* There will be better documentation and examples. + +* There will be some more formal definition of the threat model for integrity + protection. (And a link to some papers discussing integrity protection, + once it is, hopefully, accepted and published.) + +* Authenticated encryption will use new algorithms from CAESAR competition + https://competitions.cr.yp.to/caesar-submissions.html. + We plan to use AEGIS and MORUS, as CAESAR finalists. + + NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305) + in the kernel have too small 96-bit nonces that are problematic with + randomly generated IVs (the collision probability is not negligible). + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be deprecated in version 2.1 + in favor of python bindings to the libblockdev library. diff --git a/docs/v2.0.3-ReleaseNotes b/docs/v2.0.3-ReleaseNotes new file mode 100644 index 0000000..d2b209b --- /dev/null +++ b/docs/v2.0.3-ReleaseNotes @@ -0,0 +1,121 @@ +Cryptsetup 2.0.3 Release Notes +============================== +Stable bug-fix release with new features. + +Cryptsetup 2.x version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +To provide all security features of authenticated encryption, we need +a better nonce-reuse resistant algorithm in the kernel (see note below). +For now, please use authenticated encryption as an experimental feature. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Expose interface to unbound LUKS2 keyslots. + Unbound LUKS2 keyslot allows storing a key material that is independent + of master volume key (it is not bound to encrypted data segment). + +* New API extensions for unbound keyslots (LUKS2 only) + crypt_keyslot_get_key_size() and crypt_volume_key_get() + These functions allow one to get key and key size for unbound keyslots. + +* New enum value CRYPT_SLOT_UNBOUND for keyslot status (LUKS2 only). + +* Add --unbound keyslot option to the cryptsetup luksAddKey command. + +* Add crypt_get_active_integrity_failures() call to get integrity + failure count for dm-integrity devices. + +* Add crypt_get_pbkdf_default() function to get per-type PBKDF default + setting. + +* Add new flag to crypt_keyslot_add_by_key() to force update device + volume key. This call is mainly intended for a wrapped key change. + +* Allow volume key store in a file with cryptsetup. + The --dump-master-key together with --master-key-file allows cryptsetup + to store the binary volume key to a file instead of standard output. + +* Add support detached header for cryptsetup-reencrypt command. + +* Fix VeraCrypt PIM handling - use proper iterations count formula + for PBKDF2-SHA512 and PBKDF2-Whirlpool used in system volumes. + +* Fix cryptsetup tcryptDump for VeraCrypt PIM (support --veracrypt-pim). + +* Add --with-default-luks-format configure time option. + (Option to override default LUKS format version.) + +* Fix LUKS version conversion for detached (and trimmed) LUKS headers. + +* Add luksConvertKey cryptsetup command that converts specific keyslot + from one PBKDF to another. + +* Do not allow conversion to LUKS2 if LUKSMETA (external tool metadata) + header is detected. + +* More cleanup and hardening of LUKS2 keyslot specific validation options. + Add more checks for cipher validity before writing metadata on-disk. + +* Do not allow LUKS1 version downconversion if the header contains tokens. + +* Add "paes" family ciphers (AES wrapped key scheme for mainframes) + to allowed ciphers. + Specific wrapped ley configuration logic must be done by 3rd party tool, + LUKS2 stores only keyslot material and allow activation of the device. + +* Add support for --check-at-most-once option (kernel 4.17) to veritysetup. + This flag can be dangerous; if you can control underlying device + (you can change its content after it was verified) it will no longer + prevent reading tampered data and also it does not prevent silent + data corruptions that appear after the block was once read. + +* Fix return code (EPERM instead of EINVAL) and retry count for bad + passphrase on non-tty input. + +* Enable support for FEC decoding in veritysetup to check dm-verity devices + with additional Reed-Solomon code in userspace (verify command). + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* There will be better documentation and examples (planned for 2.0.4). + +* There will be some more formal definition of the threat model for integrity + protection. (And a link to some papers discussing integrity protection, + once it is, hopefully, accepted and published.) + +* Authenticated encryption will use new algorithms from CAESAR competition + https://competitions.cr.yp.to/caesar-submissions.html. + We plan to use AEGIS and MORUS, as CAESAR finalists. + + NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305) + in the kernel have too small 96-bit nonces that are problematic with + randomly generated IVs (the collision probability is not negligible). + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be REMOVED in version 2.1 + in favor of python bindings to the libblockdev library. + See https://github.com/storaged-project/libblockdev/releases/tag/2.17-1 that + already supports LUKS2 and VeraCrypt devices handling through libcryptsetup. diff --git a/docs/v2.0.4-ReleaseNotes b/docs/v2.0.4-ReleaseNotes new file mode 100644 index 0000000..9731f59 --- /dev/null +++ b/docs/v2.0.4-ReleaseNotes @@ -0,0 +1,119 @@ +Cryptsetup 2.0.4 Release Notes +============================== +Stable bug-fix release with new features. + +Cryptsetup 2.x version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +To provide all security features of authenticated encryption, we need +a better nonce-reuse resistant algorithm in the kernel (see note below). +For now, please use authenticated encryption as an experimental feature. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Use the libblkid (blockid) library to detect foreign signatures + on a device before LUKS format and LUKS2 auto-recovery. + + This change fixes an unexpected recovery using the secondary + LUKS2 header after a device was already overwritten with + another format (filesystem or LVM physical volume). + + LUKS2 will not recreate a primary header if it detects a valid + foreign signature. In this situation, a user must always + use cryptsetup repair command for the recovery. + + Note that libcryptsetup and utilities are now linked to libblkid + as a new dependence. + + To compile code without blockid support (strongly discouraged), + use --disable-blkid configure switch. + +* Add prompt for format and repair actions in cryptsetup and + integritysetup if foreign signatures are detected on the device + through the blockid library. + + After the confirmation, all known signatures are then wiped as + part of the format or repair procedure. + +* Print consistent verbose message about keyslot and token numbers. + For keyslot actions: Key slot unlocked/created/removed. + For token actions: Token created/removed. + +* Print error, if a non-existent token is tried to be removed. + +* Add support for LUKS2 token definition export and import. + + The token command now can export/import customized token JSON file + directly from command line. See the man page for more details. + +* Add support for new dm-integrity superblock version 2. + +* Add an error message when nothing was read from a key file. + +* Update cryptsetup man pages, including --type option usage. + +* Add a snapshot of LUKS2 format specification to documentation + and accordingly fix supported secondary header offsets. + +* Add bundled optimized Argon2 SSE (X86_64 platform) code. + + If the bundled Argon2 code is used and the new configure switch + --enable-internal-sse-argon2 option is present, and compiler flags + support required optimization, the code will try to use optimized + and faster variant. + + Always use the shared library (--enable-libargon2) if possible. + + This option was added because an enterprise distribution + rejected to support the shared Argon2 library and native support + in generic cryptographic libraries is not ready yet. + +* Fix compilation with crypto backend for LibreSSL >= 2.7.0. + LibreSSL introduced OpenSSL 1.1.x API functions, so compatibility + wrapper must be commented out. + +* Fix on-disk header size calculation for LUKS2 format if a specific + data alignment is requested. Until now, the code used default size + that could be wrong for converted devices. + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Authenticated encryption will use new algorithms from CAESAR competition + https://competitions.cr.yp.to/caesar-submissions.html. + We plan to use AEGIS and MORUS (in kernel 4.18), as CAESAR finalists. + + NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305) + in the kernel have too small 96-bit nonces that are problematic with + randomly generated IVs (the collision probability is not negligible). + + For more info about LUKS2 authenticated encryption, please see our paper + https://arxiv.org/abs/1807.00309 + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be REMOVED in version 2.1 + in favor of python bindings to the libblockdev library. + See https://github.com/storaged-project/libblockdev/releases that + already supports LUKS2 and VeraCrypt devices handling through libcryptsetup. + diff --git a/docs/v2.0.5-ReleaseNotes b/docs/v2.0.5-ReleaseNotes new file mode 100644 index 0000000..907d5aa --- /dev/null +++ b/docs/v2.0.5-ReleaseNotes @@ -0,0 +1,102 @@ +Cryptsetup 2.0.5 Release Notes +============================== +Stable bug-fix release with new features. + +Cryptsetup 2.x version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Wipe full header areas (including unused) during LUKS format. + + Since this version, the whole area up to the data offset is zeroed, + and subsequently, all keyslots areas are wiped with random data. + This ensures that no remaining old data remains in the LUKS header + areas, but it could slow down format operation on some devices. + Previously only first 4k (or 32k for LUKS2) and the used keyslot + was overwritten in the format operation. + +* Several fixes to error messages that were unintentionally replaced + in previous versions with a silent exit code. + More descriptive error messages were added, including error + messages if + - a device is unusable (not a block device, no access, etc.), + - a LUKS device is not detected, + - LUKS header load code detects unsupported version, + - a keyslot decryption fails (also happens in the cipher check), + - converting an inactive keyslot. + +* Device activation fails if data area overlaps with LUKS header. + +* Code now uses explicit_bzero to wipe memory if available + (instead of own implementation). + +* Additional VeraCrypt modes are now supported, including Camellia + and Kuznyechik symmetric ciphers (and cipher chains) and Streebog + hash function. These were introduced in a recent VeraCrypt upstream. + + Note that Kuznyechik requires out-of-tree kernel module and + Streebog hash function is available only with the gcrypt cryptographic + backend for now. + +* Fixes static build for integritysetup if the pwquality library is used. + +* Allows passphrase change for unbound keyslots. + +* Fixes removed keyslot number in verbose message for luksKillSlot, + luksRemoveKey and erase command. + +* Adds blkid scan when attempting to open a plain device and warn the user + about existing device signatures in a ciphertext device. + +* Remove LUKS header signature if luksFormat fails to add the first keyslot. + +* Remove O_SYNC from device open and use fsync() to speed up + wipe operation considerably. + +* Create --master-key-file in luksDump and fail if the file already exists. + +* Fixes a bug when LUKS2 authenticated encryption with a detached header + wiped the header device instead of dm-integrity data device area (causing + unnecessary LUKS2 header auto recovery). + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Authenticated encryption should use new algorithms from CAESAR competition + https://competitions.cr.yp.to/caesar-submissions.html. + AEGIS and MORUS are already available in kernel 4.18. + + For more info about LUKS2 authenticated encryption, please see our paper + https://arxiv.org/abs/1807.00309 + + Please note that authenticated encryption is still an experimental feature + and can have performance problems for hish-speed devices and device + with larger IO blocks (like RAID). + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be REMOVED in version 2.1 + in favor of python bindings to the libblockdev library. + See https://github.com/storaged-project/libblockdev/releases that + already supports LUKS2 and VeraCrypt devices handling through libcryptsetup. diff --git a/docs/v2.0.6-ReleaseNotes b/docs/v2.0.6-ReleaseNotes new file mode 100644 index 0000000..7fe276a --- /dev/null +++ b/docs/v2.0.6-ReleaseNotes @@ -0,0 +1,97 @@ +Cryptsetup 2.0.6 Release Notes +============================== +Stable bug-fix release. +All users of cryptsetup 2.0.x should upgrade to this version. + +Cryptsetup 2.x version introduces a new on-disk LUKS2 format. + +The legacy LUKS (referenced as LUKS1) will be fully supported +forever as well as a traditional and fully backward compatible format. + +Please note that authenticated disk encryption, non-cryptographic +data integrity protection (dm-integrity), use of Argon2 Password-Based +Key Derivation Function and the LUKS2 on-disk format itself are new +features and can contain some bugs. + +Please do not use LUKS2 without properly configured backup or in +production systems that need to be compatible with older systems. + +Changes since version 2.0.5 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix support of larger metadata areas in LUKS2 header. + + This release properly supports all specified metadata areas, as documented + in LUKS2 format description (see docs/on-disk-format-luks2.pdf in archive). + + Currently, only default metadata area size is used (in format or convert). + Later cryptsetup versions will allow increasing this metadata area size. + +* If AEAD (authenticated encryption) is used, cryptsetup now tries to check + if the requested AEAD algorithm with specified key size is available + in kernel crypto API. + This change avoids formatting a device that cannot be later activated. + + For this function, the kernel must be compiled with the + CONFIG_CRYPTO_USER_API_AEAD option enabled. + Note that kernel user crypto API options (CONFIG_CRYPTO_USER_API and + CONFIG_CRYPTO_USER_API_SKCIPHER) are already mandatory for LUKS2. + +* Fix setting of integrity no-journal flag. + Now you can store this flag to metadata using --persistent option. + +* Fix cryptsetup-reencrypt to not keep temporary reencryption headers + if interrupted during initial password prompt. + +* Adds early check to plain and LUKS2 formats to disallow device format + if device size is not aligned to requested sector size. + Previously it was possible, and the device was rejected to activate by + kernel later. + +* Fix checking of hash algorithms availability for PBKDF early. + Previously LUKS2 format allowed non-existent hash algorithm with + invalid keyslot preventing the device from activation. + +* Allow Adiantum cipher construction (a non-authenticated length-preserving + fast encryption scheme), so it can be used both for data encryption and + keyslot encryption in LUKS1/2 devices. + + For benchmark, use: + # cryptsetup benchmark -c xchacha12,aes-adiantum + # cryptsetup benchmark -c xchacha20,aes-adiantum + + For LUKS format: + # cryptsetup luksFormat -c xchacha20,aes-adiantum-plain64 -s 256 + + The support for Adiantum will be merged in Linux kernel 4.21. + For more info see the paper https://eprint.iacr.org/2018/720. + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Authenticated encryption should use new algorithms from CAESAR competition + https://competitions.cr.yp.to/caesar-submissions.html. + AEGIS and MORUS are already available in kernel 4.18. + + For more info about LUKS2 authenticated encryption, please see our paper + https://arxiv.org/abs/1807.00309 + + Please note that authenticated encryption is still an experimental feature + and can have performance problems for high-speed devices and device + with larger IO blocks (like RAID). + +* Authenticated encryption do not set encryption for a dm-integrity journal. + + While it does not influence data confidentiality or integrity protection, + an attacker can get some more information from data journal or cause that + system will corrupt sectors after journal replay. (That corruption will be + detected though.) + +* There are examples of user-defined tokens inside misc/luks2_keyslot_example + directory (like a simple external program that uses libssh to unlock LUKS2 + using remote keyfile). + +* The python binding (pycryptsetup) contains only basic functionality for LUKS1 + (it is not updated for new features) and will be REMOVED in version 2.1 + in favor of python bindings to the libblockdev library. + See https://github.com/storaged-project/libblockdev/releases that + already supports LUKS2 and VeraCrypt devices handling through libcryptsetup. diff --git a/docs/v2.1.0-ReleaseNotes b/docs/v2.1.0-ReleaseNotes new file mode 100644 index 0000000..87222cb --- /dev/null +++ b/docs/v2.1.0-ReleaseNotes @@ -0,0 +1,210 @@ +Cryptsetup 2.1.0 Release Notes +============================== +Stable release with new features and bug fixes. + +Cryptsetup 2.1 version uses a new on-disk LUKS2 format as the default +LUKS format and increases default LUKS2 header size. + +The legacy LUKS (referenced as LUKS1) will be fully supported forever +as well as a traditional and fully backward compatible format. + +When upgrading a stable distribution, please use configure option +--with-default-luks-format=LUKS1 to maintain backward compatibility. + +This release also switches to OpenSSL as a default cryptographic +backend for LUKS header processing. Use --with-crypto_backend=gcrypt +configure option if you need to preserve legacy libgcrypt backend. + +Please do not use LUKS2 without properly configured backup or +in production systems that need to be compatible with older systems. + +Changes since version 2.0.6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* The default for cryptsetup LUKS format action is now LUKS2. + You can use LUKS1 with cryptsetup option --type luks1. + +* The default size of the LUKS2 header is increased to 16 MB. + It includes metadata and the area used for binary keyslots; + it means that LUKS header backup is now 16MB in size. + + Note, that used keyslot area is much smaller, but this increase + of reserved space allows implementation of later extensions + (like online reencryption). + It is fully compatible with older cryptsetup 2.0.x versions. + If you require to create LUKS2 header with the same size as + in the 2.0.x version, use --offset 8192 option for luksFormat + (units are in 512-bytes sectors; see notes below). + +* Cryptsetup now doubles LUKS default key size if XTS mode is used + (XTS mode uses two internal keys). This does not apply if key size + is explicitly specified on the command line and it does not apply + for the plain mode. + This fixes a confusion with AES and 256bit key in XTS mode where + code used AES128 and not AES256 as often expected. + + Also, the default keyslot encryption algorithm (if cannot be derived + from data encryption algorithm) is now available as configure + options --with-luks2-keyslot-cipher and --with-luks2-keyslot-keybits. + The default is aes-xts-plain64 with 2 * 256-bits key. + +* Default cryptographic backend used for LUKS header processing is now + OpenSSL. For years, OpenSSL provided better performance for PBKDF. + + NOTE: Cryptsetup/libcryptsetup supports several cryptographic + library backends. The fully supported are libgcrypt, OpenSSL and + kernel crypto API. FIPS mode extensions are maintained only for + libgcrypt and OpenSSL. Nettle and NSS are usable only for some + subset of algorithms and cannot provide full backward compatibility. + You can always switch to other backends by using a configure switch, + for libgcrypt (compatibility for older distributions) use: + --with-crypto_backend=gcrypt + +* The Python bindings are no longer supported and the code was removed + from cryptsetup distribution. Please use the libblockdev project + that already covers most of the libcryptsetup functionality + including LUKS2. + +* Cryptsetup now allows using --offset option also for luksFormat. + It means that the specified offset value is used for data offset. + LUKS2 header areas are automatically adjusted according to this value. + (Note units are in 512-byte sectors due to the previous definition + of this option in plain mode.) + This option can replace --align-payload with absolute alignment value. + +* Cryptsetup now supports new refresh action (that is the alias for + "open --refresh"). + It allows changes of parameters for an active device (like root + device mapping), for example, it can enable or disable TRIM support + on-the-fly. + It is supported for LUKS1, LUKS2, plain and loop-AES devices. + +* Integritysetup now supports mode with detached data device through + new --data-device option. + Since kernel 4.18 there is a possibility to specify external data + device for dm-integrity that stores all integrity tags. + +* Integritysetup now supports automatic integrity recalculation + through new --integrity-recalculate option. + Linux kernel since version 4.18 supports automatic background + recalculation of integrity tags for dm-integrity. + +Other changes and fixes +~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix for crypt_wipe call to allocate space if the header is backed + by a file. This means that if you use detached header file, it will + now have always the full size after luksFormat, even if only + a few keyslots are used. + +* Fixes to offline cryptsetup-reencrypt to preserve LUKS2 keyslots + area sizes after reencryption and fixes for some other issues when + creating temporary reencryption headers. + +* Added some FIPS mode workarounds. We cannot (yet) use Argon2 in + FIPS mode, libcryptsetup now fallbacks to use PBKDF2 in FIPS mode. + +* Rejects conversion to LUKS1 if PBKDF2 hash algorithms + in keyslots differ. + +* The hash setting on command line now applies also to LUKS2 PBKDF2 + digest. In previous versions, the LUKS2 key digest used PBKDF2-SHA256 + (except for converted headers). + +* Allow LUKS2 keyslots area to increase if data offset allows it. + Cryptsetup can fine-tune LUKS2 metadata area sizes through + --luks2-metadata-size=BYTES and --luks2-keyslots-size=BYTES. + Please DO NOT use these low-level options until you need it for + some very specific additional feature. + Also, the code now prints these LUKS2 header area sizes in dump + command. + +* For LUKS2, keyslot can use different encryption that data with + new options --keyslot-key-size=BITS and --keyslot-cipher=STRING + in all commands that create new LUKS keyslot. + Please DO NOT use these low-level options until you need it for + some very specific additional feature. + +* Code now avoids data flush when reading device status through + device-mapper. + +* The Nettle crypto backend and the userspace kernel crypto API + backend were enhanced to allow more available hash functions + (like SHA3 variants). + +* Upstream code now does not require libgcrypt-devel + for autoconfigure, because OpenSSL is the default. + The libgcrypt does not use standard pkgconfig detection and + requires specific macro (part of libgcrypt development files) + to be always present during autoconfigure. + With other crypto backends, like OpenSSL, this makes no sense, + so this part of autoconfigure is now optional. + +* Cryptsetup now understands new --debug-json option that allows + an additional dump of some JSON information. These are no longer + present in standard debug output because it could contain some + specific LUKS header parameters. + +* The luksDump contains the hash algorithm used in Anti-Forensic + function. + +* All debug messages are now sent through configured log callback + functions, so an application can easily use own debug messages + handling. In previous versions debug messages were printed directly + to standard output.) + +Libcryptsetup API additions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These new calls are now exported, for details see libcryptsetup.h: + + * crypt_init_data_device + * crypt_get_metadata_device_name + functions to init devices with separate metadata and data device + before a format function is called. + + * crypt_set_data_offset + sets the data offset for LUKS to the specified value + in 512-byte sectors. + It should replace alignment calculation in LUKS param structures. + + * crypt_get_metadata_size + * crypt_set_metadata_size + allows one to set/get area sizes in LUKS header + (according to specification). + + * crypt_get_default_type + get default compiled-in LUKS type (version). + + * crypt_get_pbkdf_type_params + allows one to get compiled-in PBKDF parameters. + + * crypt_keyslot_set_encryption + * crypt_keyslot_get_encryption + allows one to set/get per-keyslot encryption algorithm for LUKS2. + + * crypt_keyslot_get_pbkdf + allows one to get PBKDF parameters per-keyslot. + + and these new defines: + * CRYPT_LOG_DEBUG_JSON (message type for JSON debug) + * CRYPT_DEBUG_JSON (log level for JSON debug) + * CRYPT_ACTIVATE_RECALCULATE (dm-integrity recalculate flag) + * CRYPT_ACTIVATE_REFRESH (new open with refresh flag) + +All existing API calls should remain backward compatible. + +Unfinished things & TODO for next releases +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* Optional authenticated encryption is still an experimental feature + and can have performance problems for high-speed devices and device + with larger IO blocks (like RAID). + +* Authenticated encryption does not use encryption for a dm-integrity + journal. While it does not influence data confidentiality or + integrity protection, an attacker can get some more information + from data journal or cause that system will corrupt sectors after + journal replay. (That corruption will be detected though.) + +* The LUKS2 metadata area increase is mainly needed for the new online + reencryption as the major feature for the next release. diff --git a/docs/v2.2.0-ReleaseNotes b/docs/v2.2.0-ReleaseNotes new file mode 100644 index 0000000..b1fd363 --- /dev/null +++ b/docs/v2.2.0-ReleaseNotes @@ -0,0 +1,279 @@ +Cryptsetup 2.2.0 Release Notes +============================== +Stable release with new experimental features and bug fixes. + +Cryptsetup 2.2 version introduces a new LUKS2 online reencryption +extension that allows reencryption of mounted LUKS2 devices +(device in use) in the background. + +Online reencryption is a complex feature. Please be sure you +have a full data backup before using this feature. + +Changes since version 2.1.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +LUKS2 online reencryption +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reencryption is intended to provide a reliable way to change +volume key or an algorithm change while the encrypted device is still +in use. + +It is based on userspace-only approach (no kernel changes needed) +that uses the device-mapper subsystem to remap active devices on-the-fly +dynamically. The device is split into several segments (encrypted by old +key, new key and so-called hotzone, where reencryption is actively running). + +The flexible LUKS2 metadata format is used to store intermediate states +(segment mappings) and both version of keyslots (old and new keys). +Also, it provides a binary area (in the unused keyslot area space) +to provide recovery metadata in the case of unexpected failure during +reencryption. LUKS2 header is during the reencryption marked with +"online-reencryption" keyword. After the reencryption is finished, +this keyword is removed, and the device is backward compatible with all +older cryptsetup tools (that support LUKS2). + +The recovery supports three resilience modes: + + - checksum: default mode, where individual checksums of ciphertext hotzone + sectors are stored, so the recovery process can detect which sectors were + already reencrypted. It requires that the device sector write is atomic. + + - journal: the hotzone is journaled in the binary area + (so the data are written twice) + + - none: performance mode; there is no protection + (similar to old offline reencryption) + +These resilience modes are not available if reencryption uses data shift. + +Note: until we have full documentation (both of the process and metadata), +please refer to Ondrej's slides (some slight details are no longer relevant) +https://okozina.fedorapeople.org/online-disk-reencryption-with-luks2-compact.pdf + +The offline reencryption tool (cryptsetup-reencrypt) is still supported +for both LUKS1 and LUKS2 format. + +Cryptsetup examples for reencryption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The reencryption feature is integrated directly into cryptsetup utility +as the new "reencrypt" action (command). + +There are three basic modes - to perform reencryption (change of already +existing LUKS2 device), to add encryption to plaintext device and to remove +encryption from a device (decryption). + +In all cases, if existing LUKS2 metadata contains information about +the ongoing reencryption process, following reencrypt command continues +with the ongoing reencryption process until it is finished. + +You can activate a device with ongoing reencryption as the standard LUKS2 +device, but the reencryption process will not continue until the cryptsetup +reencrypt command is issued. + + +1) Reencryption +~~~~~~~~~~~~~~~ +This mode is intended to change any attribute of the data encryption +(change of the volume key, algorithm or sector size). +Note that authenticated encryption is not yet supported. + +You can start the reencryption process by specifying a LUKS2 device or with +a detached LUKS2 header. +The code should automatically recognize if the device is in use (and if it +should use online mode of reencryption). + +If you do not specify parameters, only volume key is changed +(a new random key is generated). + +# cryptsetup reencrypt [--header ] + +You can also start reencryption using active mapped device name: + # cryptsetup reencrypt --active-name + +You can also specify the resilience mode (none, checksum, journal) with +--resilience= option, for checksum mode also the hash algorithm with +--resilience-hash= (only hash algorithms supported by cryptographic +backend are available). + +The maximal size of reencryption hotzone can be limited by +--hotzone-size= option and applies to all reencryption modes. +Note that for checksum and journal mode hotzone size is also limited +by available space in binary keyslot area. + +2) Encryption +~~~~~~~~~~~~~ +This mode provides a way to encrypt a plaintext device to LUKS2 format. +This option requires reduction of device size (for LUKS2 header) or new +detached header. + + # cryptsetup reencrypt --encrypt --reduce-device-size + +Or with detached header: + # cryptsetup reencrypt --encrypt --header + +3) Decryption +~~~~~~~~~~~~~ +This mode provides the removal of existing LUKS2 encryption and replacing +a device with plaintext content only. +For now, we support only decryption with a detached header. + + # cryptsetup reencrypt --decrypt --header + +For all three modes, you can split the process to metadata initialization +(prepare keyslots and segments but do not run reencryption yet) and the data +reencryption step by using --init-only option. + +Prepares metadata: + # cryptsetup reencrypt --init-only + +Starts the data processing: + # cryptsetup reencrypt + +Please note, that due to the Linux kernel limitation, the encryption or +decryption process cannot be run entirely online - there must be at least +short offline window where operation adds/removes device-mapper crypt (LUKS2) layer. +This step should also include modification of /etc/crypttab and fstab UUIDs, +but it is out of the scope of cryptsetup tools. + +Limitations +~~~~~~~~~~~ +Most of these limitations will be (hopefully) fixed in next versions. + +* Only one active keyslot is supported (all old keyslots will be removed + after reencryption). + +* Only block devices are now supported as parameters. As a workaround + for images in a file, please explicitly map a loop device over the image + and use the loop device as the parameter. + +* Devices with authenticated encryption are not supported. (Later it will + be limited by the fixed per-sector metadata, per-sector metadata size + cannot be changed without a new device format operation.) + +* The reencryption uses userspace crypto library, with fallback to + the kernel (if available). There can be some specific configurations + where the fallback does not provide optimal performance. + +* There are no translations of error messages until the final release + (some messages can be rephrased as well). + +* The repair command is not finished; the recovery of interrupted + reencryption is made automatically on the first device activation. + +* Reencryption triggers too many udev scans on metadata updates (on closing + write enabled file descriptors). This has a negative performance impact on the whole + reencryption and generates excessive I/O load on the system. + +New libcryptsetup reencryption API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The libcryptsetup contains new API calls that are used to setup and +run the reencryption. + +Note that there can be some changes in API implementation of these functions +and/or some new function can be introduced in final cryptsetup 2.2 release. + +New API symbols (see documentation in libcryptsetup.h) +* struct crypt_params_reencrypt - reencryption parameters + +* crypt_reencrypt_init_by_passphrase +* crypt_reencrypt_init_by_keyring + - function to configure LUKS2 metadata for reencryption; + if metadata already exists, it configures the context from this metadata + +* crypt_reencrypt + - run the reencryption process (processing the data) + - the optional callback function can be used to interrupt the reencryption + or report the progress. + +* crypt_reencrypt_status + - function to query LUKS2 metadata about the reencryption state + +Other changes and fixes +~~~~~~~~~~~~~~~~~~~~~~~ +* Add optional global serialization lock for memory hard PBKDF. + (The --serialize-memory-hard-pbkdf option in cryptsetup and + CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF in activation flag.) + + This is an "ugly" optional workaround for a situation when multiple devices + are being activated in parallel (like systemd crypttab activation). + The system instead of returning ENOMEM (no memory available) starts + out-of-memory (OOM) killer to kill processes randomly. + + Until we find a reliable way how to work with memory-hard function + in these situations, cryptsetup provide a way how to serialize memory-hard + unlocking among parallel cryptsetup instances to workaround this problem. + This flag is intended to be used only in very specific situations, + never use it directly :-) + +* Abort conversion to LUKS1 with incompatible sector size that is + not supported in LUKS1. + +* Report error (-ENOENT) if no LUKS keyslots are available. User can now + distinguish between a wrong passphrase and no keyslot available. + +* Fix a possible segfault in detached header handling (double free). + +* Add integritysetup support for bitmap mode introduced in Linux kernel 5.2. + Integritysetup now supports --integrity-bitmap-mode option and + --bitmap-sector-per-bit and --bitmap-flush-time commandline options. + + In the bitmap operation mode, if a bit in the bitmap is 1, the corresponding + region's data and integrity tags are not synchronized - if the machine + crashes, the unsynchronized regions will be recalculated. + The bitmap mode is faster than the journal mode because we don't have + to write the data twice, but it is also less reliable, because if data + corruption happens when the machine crashes, it may not be detected. + This can be used only for standalone devices, not with dm-crypt. + +* The libcryptsetup now keeps all file descriptors to underlying device + open during the whole lifetime of crypt device context to avoid excessive + scanning in udev (udev run scan on every descriptor close). + +* The luksDump command now prints more info for reencryption keyslot + (when a device is in-reencryption). + +* New --device-size parameter is supported for LUKS2 reencryption. + It may be used to encrypt/reencrypt only the initial part of the data + device if the user is aware that the rest of the device is empty. + + Note: This change causes API break since the last rc0 release + (crypt_params_reencrypt structure contains additional field). + +* New --resume-only parameter is supported for LUKS2 reencryption. + This flag resumes reencryption process if it exists (not starting + new reencryption). + +* The repair command now tries LUKS2 reencryption recovery if needed. + +* If reencryption device is a file image, an interactive dialog now + asks if reencryption should be run safely in offline mode + (if autodetection of active devices failed). + +* Fix activation through a token where dm-crypt volume key was not + set through keyring (but using old device-mapper table parameter mode). + +* Online reencryption can now retain all keyslots (if all passphrases + are provided). Note that keyslot numbers will change in this case. + +* Allow volume key file to be used if no LUKS2 keyslots are present. + If all keyslots are removed, LUKS2 has no longer information about + the volume key size (there is only key digest present). + Please use --key-size option to open the device or add a new keyslot + in these cases. + +* Print a warning if online reencrypt is called over LUKS1 (not supported). + +* Fix TCRYPT KDF failure in FIPS mode. + Some crypto backends support plain hash in FIPS mode but not for PBKDF2. + +* Remove FIPS mode restriction for crypt_volume_key_get. + It is an application responsibility to use this API in the proper context. + +* Reduce keyslots area size in luksFormat when the header device is too small. + Unless user explicitly asks for keyslots areas size (either via + --luks2-keyslots-size or --offset) reduce keyslots size so that it fits + in metadata device. + +* Make resize action accept --device-size parameter (supports units suffix). diff --git a/docs/v2.2.1-ReleaseNotes b/docs/v2.2.1-ReleaseNotes new file mode 100644 index 0000000..34bacc1 --- /dev/null +++ b/docs/v2.2.1-ReleaseNotes @@ -0,0 +1,36 @@ +Cryptsetup 2.2.1 Release Notes +============================== +Stable bug-fix release. + +This version contains a fix for a possible data corruption bug +on 32-bit platforms. +All users of cryptsetup 2.1 and 2.2 should upgrade to this version. + +Changes since version 2.2.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix possible data length and IV offset overflow on 32bit architectures. + Other 64-bit architectures are not affected. + + The flawed helper function prototypes (introduced in version 2.1.0) used + size_t type, that is 32-bit integer on 32-bit systems. + This patch fixes the problem to properly use 64-bit types. + + If the offset parameter addresses devices larger than 2TB, the value + overflows and stores incorrect information in the metadata. + For example, integrity device is smaller than expected size if used + over large disk on 32-bit architecture. + + This issue is not present with the standard LUKS1/LUKS2 devices without + integrity extensions. + +* Fix a regression in TrueCrypt/VeraCrypt system partition activation. + +* Reinstate missing backing file hint for loop device. + + If the encrypted device is backed by a file (loopback), cryptsetup now + shows the path to the backing file in passphrase query (as in 1.x version). + +* LUKS2 reencryption block size is now aligned to reported optimal IO size. + This change eliminates possible non-aligned device warnings in kernel log + during reencryption. diff --git a/docs/v2.2.2-ReleaseNotes b/docs/v2.2.2-ReleaseNotes new file mode 100644 index 0000000..9e68641 --- /dev/null +++ b/docs/v2.2.2-ReleaseNotes @@ -0,0 +1,56 @@ +Cryptsetup 2.2.2 Release Notes +============================== +Stable bug-fix release. + +All users of cryptsetup 2.1 and 2.2 should upgrade to this version. + +Changes since version 2.2.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Print error message if a keyslot open failed for a different reason + than wrong passwords (for example there is not enough memory). + Only an exit code was present in this case. + +* The progress function switches unit sizes (B/s to GiB/s) according + to the actual speed. Also, it properly calculates speed in the case + of a resumed reencryption operation. + +* The --version now supports short -V short option and better handles + common option priorities. + +* If cryptsetup wipes signatures during format actions through blkid, + it also prints signature device offsets. + +* Compilation now properly uses LTLIBINTL gettext setting in Makefiles. + +* Device-mapper backend now supports new DM_GET_TARGET_VERSION ioctl + (available since Linux kernel 5.4). + This should help to detect some kernel/userspace incompatibilities + earlier later after a failed device activation. + +* Fixes LUKS2 reencryption on systems without kernel keyring. + +* Fixes unlocking prompt for partitions mapped through loop devices + (to properly show the backing device). + +* For LUKS2 decryption, a device is now marked for deferred removal + to be automatically deactivated. + +* Reencryption now limits hotzone size to be maximal 1 GiB or 1/4 + system memory (if lower). + +* Reencryption now retains activation flags during online reencryption. + +* Reencryption now allows LUKS2 device to activate device right after + LUKS2 encryption is initialized through optional active device name + for cryptsetup reencrypt --encrypt command. + This could help with automated encryption during boot. + + NOTE: It means that part of the device is still not encrypted during + activation. Use with care! + +* Fixes failure in resize and plain format activation if activated device + size was not aligned to underlying logical device size. + +* Fixes conversion to LUKS2 format with detached header if a detached + header size was smaller than the expected aligned LUKS1 header size. diff --git a/docs/v2.3.0-ReleaseNotes b/docs/v2.3.0-ReleaseNotes new file mode 100644 index 0000000..a3eb3ec --- /dev/null +++ b/docs/v2.3.0-ReleaseNotes @@ -0,0 +1,209 @@ +Cryptsetup 2.3.0 Release Notes +============================== +Stable release with new experimental features and bug fixes. + +Cryptsetup 2.3 version introduces support for BitLocker-compatible +devices (BITLK format). This format is used in Windows systems, +and in combination with a filesystem driver, cryptsetup now provides +native read-write access to BitLocker Full Disk Encryption devices. + +The BITLK implementation is based on publicly available information +and it is an independent and opensource implementation that allows +one to access this proprietary disk encryption. + +Changes since version 2.2.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* BITLK (Windows BitLocker compatible) device access + + BITLK userspace implementation is based on the master thesis and code + provided by Vojtech Trefny. Also, thanks to other opensource projects + like libbde (that provide alternative approach to decode this format) + we were able to verify cryptsetup implementation. + + NOTE: Support for the BITLK device is EXPERIMENTAL and will require + a lot of testing. If you get some error message (mainly unsupported + metadata in the on-disk header), please help us by submitting an issue + to cryptsetup project, so we can fix it. Thank you! + + Cryptsetup supports BITLK activation through passphrase or recovery + passphrase for existing devices (BitLocker and Bitlocker to Go). + + Activation through TPM, SmartCard, or any other key protector + is not supported. And in some situations, mainly for TPM bind to some + PCR registers, it could be even impossible on Linux in the future. + + All metadata (key protectors) are handled read-only, cryptsetup cannot + create or modify them. Except for old devices (created in old Vista + systems), all format variants should be recognized. + + Data devices can be activated read-write (followed by mounting through + the proper filesystem driver). To access filesystem on the decrypted device + you need properly installed driver (vfat, NTFS or exFAT). + + Foe AES-XTS, activation is supported on all recent Linux kernels. + + For older AES-CBC encryption, Linux Kernel version 5.3 is required + (support for special IV variant); for AES-CBC with Elephant diffuser, + Linux Kernel 5.6 is required. + + Please note that CBC variants are legacy, and we provide it only + for backward compatibility (to be able to access old drives). + + Cryptsetup command now supports the new "bitlk" format and implement dump, + open, status, and close actions. + + To activate a BITLK device, use + + # cryptsetup open --type bitlk + or with alias + # cryptsetup bitlkOpen + + Then with properly installed fs driver (usually NTFS, vfat or exFAT), + you can mount the plaintext device /dev/mapper device as a common + filesystem. + + To print metadata information about BITLK device, use + # crypotsetup bitlkDump + + To print information about the active device, use + # cryptsetup status + + Example (activation of disk image): + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + # Recent blkid recognizes BitLocker device,just to verity + # blkid bitlocker_xts_ntfs.img + bitlocker_xts_ntfs.img: TYPE="BitLocker" + + # Print visible metadata information (on-disk, form the image) + # cryptsetup bitlkDump bitlocker_xts_ntfs.img + Info for BITLK device bitlocker_xts_ntfs.img. + Version: 2 + GUID: ... + Created: Wed Oct 23 17:38:15 2019 + Description: DESKTOP-xxxxxxx E: 23.10.2019 + Cipher name: aes + Cipher mode: xts-plain64 + Cipher key: 128 bits + + Keyslots: + 0: VMK + GUID: ... + Protection: VMK protected with passphrase + Salt: ... + Key data size: 44 [bytes] + 1: VMK + GUID: ... + Protection: VMK protected with recovery passphrase + Salt: ... + Key data size: 44 [bytes] + 2: FVEK + Key data size: 44 [bytes] + + # Activation (recovery passphrase works the same as password) + # cryptsetup bitlkOpen bitlocker_xts_ntfs.img test -v + Enter passphrase for bitlocker_xts_ntfs.img: + Command successful. + + # Information about the active device + # cryptsetup status test + /dev/mapper/test is active. + type: BITLK + cipher: aes-xts-plain64 + keysize: 128 bits + ... + + # Plaintext device should now contain decrypted NTFS filesystem + # blkid /dev/mapper/test + /dev/mapper/test: UUID="..." TYPE="ntfs" + + # And can be mounted + # mount /dev/mapper/test /mnt/tst + + # Deactivation + # umount /mnt/tst + # cryptsetup close test + +* Veritysetup now supports activation with additional PKCS7 signature + of root hash through --root-hash-signature option. + The signature uses an in-kernel trusted key to validate the signature + of the root hash during activation. This option requires Linux kernel + 5.4 with DM_VERITY_VERIFY_ROOTHASH_SIG option. + + Verity devices activated with signature now has a special flag + (with signature) active in device status (veritysetup status ). + + Usage: + # veritysetup open name \ + --root-hash-signature= + +* Integritysetup now calculates hash integrity size according to algorithm + instead of requiring an explicit tag size. + + Previously, when integritysetup formats a device with hash or + HMAC integrity checksums, it required explicitly tag size entry from + a user (or used default value). + This led to confusion and unexpected shortened tag sizes. + + Now, libcryptsetup calculates tag size according to real hash output. + Tag size can also be specified, then it warns if these values differ. + +* Integritysetup now supports fixed padding for dm-integrity devices. + + There was an in-kernel bug that wasted a lot of space when using metadata + areas for integrity-protected devices if a larger sector size than + 512 bytes was used. + This problem affects both stand-alone dm-integrity and also LUKS2 with + authenticated encryption and larger sector size. + + The new extension to dm-integrity superblock is needed, so devices + with the new optimal padding cannot be activated on older systems. + + Integritysetup/Cryptsetup will use new padding automatically if it + detects the proper kernel. To create a compatible device with + the old padding, use --integrity-legacy-padding option. + +* A lot of fixes to online LUKS2 reecryption. + +* Add crypt_resume_by_volume_key() function to libcryptsetup. + If a user has a volume key available, the LUKS device can be resumed + directly using the provided volume key. + No keyslot derivation is needed, only the key digest is checked. + +* Implement active device suspend info. + Add CRYPT_ACTIVATE_SUSPENDED bit to crypt_get_active_device() flags + that informs the caller that device is suspended (luksSuspend). + +* Allow --test-passphrase for a detached header. + Before this fix, we required a data device specified on the command + line even though it was not necessary for the passphrase check. + +* Allow --key-file option in legacy offline encryption. + The option was ignored for LUKS1 encryption initialization. + +* Export memory safe functions. + To make developing of some extensions simpler, we now export + functions to handle memory with proper wipe on deallocation. + +* Fail crypt_keyslot_get_pbkdf for inactive LUKS1 keyslot. + +Libcryptsetup API extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The libcryptsetup API is backward compatible for existing symbols. + +New symbols + crypt_set_compatibility + crypt_get_compatibility; + crypt_resume_by_volume_key; + crypt_activate_by_signed_key; + crypt_safe_alloc; + crypt_safe_realloc; + crypt_safe_free; + crypt_safe_memzero; + +New defines introduced : + CRYPT_BITLK "BITLK" - BITLK (BitLocker-compatible mode + CRYPT_COMPAT_LEGACY_INTEGRITY_PADDING - dm-integrity legacy padding + CRYPT_VERITY_ROOT_HASH_SIGNATURE - dm-verity root hash signature + CRYPT_ACTIVATE_SUSPENDED - device suspended info flag diff --git a/docs/v2.3.1-ReleaseNotes b/docs/v2.3.1-ReleaseNotes new file mode 100644 index 0000000..1c1d365 --- /dev/null +++ b/docs/v2.3.1-ReleaseNotes @@ -0,0 +1,45 @@ +Cryptsetup 2.3.1 Release Notes +============================== +Stable bug-fix release. + +All users of cryptsetup 2.x should upgrade to this version. + +Changes since version 2.3.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Support VeraCrypt 128 bytes passwords. + VeraCrypt now allows passwords of maximal length 128 bytes + (compared to legacy TrueCrypt where it was limited by 64 bytes). + +* Strip extra newline from BitLocker recovery keys + There might be a trailing newline added by the text editor when + the recovery passphrase was passed using the --key-file option. + +* Detect separate libiconv library. + It should fix compilation issues on distributions with iconv + implemented in a separate library. + +* Various fixes and workarounds to build on old Linux distributions. + +* Split lines with hexadecimal digest printing for large key-sizes. + +* Do not wipe the device with no integrity profile. + With --integrity none we performed useless full device wipe. + +* Workaround for dm-integrity kernel table bug. + Some kernels show an invalid dm-integrity mapping table + if superblock contains the "recalculate" bit. This causes + integritysetup to not recognize the dm-integrity device. + Integritysetup now specifies kernel options such a way that + even on unpatched kernels mapping table is correct. + +* Print error message if LUKS1 keyslot cannot be processed. + If the crypto backend is missing support for hash algorithms + used in PBKDF2, the error message was not visible. + +* Properly align LUKS2 keyslots area on conversion. + If the LUKS1 payload offset (data offset) is not aligned + to 4 KiB boundary, new LUKS2 keyslots area in now aligned properly. + +* Validate LUKS2 earlier on conversion to not corrupt the device + if binary keyslots areas metadata are not correct. diff --git a/docs/v2.3.2-ReleaseNotes b/docs/v2.3.2-ReleaseNotes new file mode 100644 index 0000000..b8b8250 --- /dev/null +++ b/docs/v2.3.2-ReleaseNotes @@ -0,0 +1,42 @@ +Cryptsetup 2.3.2 Release Notes +============================== +Stable bug-fix release. + +All users of cryptsetup 2.x should upgrade to this version. + +Changes since version 2.3.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Support compilation with json-c library version 0.14. + +* Update FAQ document for some LUKS2 specific information. + +* Add option to dump content of LUKS2 unbound keyslot: + cryptsetup luksDump --unbound -S + or optionally with --master-key-file option. + + The slot number --key-slot (-S) option is mandatory here. + + An unbound keyslot store a key is that is not assigned to data + area on disk (LUKS2 allows one to store arbitrary keys). + +* Rephrase some error messages and remove redundant end-of-lines. + +* Add support for discards (TRIM) for standalone dm-integrity devices. + Linux kernel 5.7 adds support for optional discard/TRIM operation + over dm-integrity devices. + + It is now supported through --allow-discards integritysetup option. + Note you need to add this flag in all activation calls. + + Note that this option cannot be used for LUKS2 authenticated encryption + (that uses dm-integrity for storing additional per-sector metadata). + +* Fix cryptsetup-reencrypt to work on devices that do not allow + direct-io device access. + +* Fix a crash in the BitLocker-compatible code error path. + +* Fix Veracrypt compatible support for longer (>64 bytes) passphrases. + It allows some older images to be correctly opened again. + The issue was introduced in version 2.3.1. diff --git a/docs/v2.3.3-ReleaseNotes b/docs/v2.3.3-ReleaseNotes new file mode 100644 index 0000000..75471ac --- /dev/null +++ b/docs/v2.3.3-ReleaseNotes @@ -0,0 +1,42 @@ +Cryptsetup 2.3.3 Release Notes +============================== +Stable bug-fix release. + +All users of cryptsetup 2.x should upgrade to this version. + +Changes since version 2.3.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix BitLocker compatible device access that uses native 4kB sectors. + + Devices formatted with storage that natively support 4096-bytes + sectors can also use this sector size for encryption units. + +* Support large IV count (--iv-large-sectors) cryptsetup option + for plain device mapping. + + The large IV count is supported in dm-crypt together with larger + sector encryption. It counts the Initialization Vector (IV) in + a larger sector size instead of 512-bytes sectors. + + This option does not have any performance or security impact, + but it can be used for accessing incompatible existing disk images + from other systems. + + Only open action with plain device type and sector size > 512 bytes + are supported. + +* Fix a memory leak in BitLocker compatible handling. + +* Allow EBOIV (Initialization Vector algorithm) use. + + The EBOIV initialization vector is intended to be used internally + with BitLocker devices (for CBC mode). It can now be used also + outside of the BitLocker compatible code. + +* Require both keyslot cipher and key size options. + + If these LUKS2 keyslot parameters were not specified together, + cryptsetup silently failed. + +* Update to man pages and FAQ. diff --git a/docs/v2.3.4-ReleaseNotes b/docs/v2.3.4-ReleaseNotes new file mode 100644 index 0000000..46c5f14 --- /dev/null +++ b/docs/v2.3.4-ReleaseNotes @@ -0,0 +1,112 @@ +Cryptsetup 2.3.4 Release Notes +============================== +Stable bug-fix release with a security fix (32-bit only). + +All users of cryptsetup 2.2.x and later should upgrade to this version. + +Changes since version 2.3.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix a possible out-of-bounds memory write while validating LUKS2 data + segments metadata (CVE-2020-14382). + + This problem can be triggered only on 32-bit builds (64-bit systems + are not affected). + + LUKS2 format validation code contains a bug in segments validation code + where the code does not check for possible overflow on memory allocation. + + Due to the bug, the libcryptsetup can be tricked to expect such allocation + was successful. Later it may read data from image crafted by an attacker and + actually write such data beyond allocated memory. + + The bug was introduced in cryptsetup 2.2.0. All later releases until 2.3.4 + are affected. + + If you only backport the fix for this CVE, these master branch git commits + should be backported: + 52f5cb8cedf22fb3e14c744814ec8af7614146c7 + 46ee71edcd13e1dad50815ad65c28779aa6f7503 + 752c9a52798f11d3b765b673ebaa3058eb25316e + + Thanks to Tobias Stoeckmann for discovering this issue. + +* Ignore reported optimal IO size if not aligned to minimal page size. + + Some USB enclosures report bogus block device topology (see lsblk -t) that + prevents LUKS2 format with 4k sector size (reported values are not correctly + aligned). The code now ignores such values and uses the default alignment. + +* Added support for new no_read/write_wrokqueue dm-crypt options (kernel 5.9). + + These performance options, introduced in kernel 5.9, configure dm-crypt + to bypass read or write workqueues and run encryption synchronously. + + Use --perf-no_read_workqueue or --perf-no_write_workqueue cryptsetup arguments + to use these dm-crypt flags. + + These options are available only for low-level dm-crypt performance tuning, + use only if you need a change to default dm-crypt behavior. + + For LUKS2, these flags can be persistently stored in metadata with + the --persistent option. + +* Added support panic_on_corruption option for dm-verity devices (kernel 5.9). + + Veritysetup now supports --panic-on-corruption argument that configures + the dm-verity device to panics kernel if a corruption is detected. + + This option is intended for specific configurations, do not use it in + standard configurations. + +* Support --master-key-file option for online LUKS2 reencryption + + This can be used for reencryption of devices that uses protected key AES cipher + on some mainframes crypto accelerators. + +* Always return EEXIST error code if a device already exists. + + Some libcryptsetup functions (activate_by*) now return EEXIST error code, + so the caller can distinguish that call fails because some parallel process + already activated the device. + Previously all fails returned EINVAL (invalid value). + +* Fix a problem in integritysetup if a hash algorithm has dash in the name. + + If users want to use blake2b/blake2s, the kernel algorithm name includes + a dash (like "blake2s-256"). + These algorithms can now be used for integritysetup devices. + +* Fix crypto backend to properly handle ECB mode. + + Even though it should never be used, it should still work for testing :) + This fixes a bug introduced in cryptsetup version 2.3.2. + +* TrueCrypt/VeraCrypt compatible mode now supports the activation of devices + with a larger sector. + + TrueCrypt/VeraCrypt always uses 512-byte sector for encryption, but for devices + with a larger native sector, it stores this value in the header. + + This patch allows activation of such devices, basically ignoring + the mentioned sector size. + +* LUKS2: Do not create excessively large headers. + + When creating a LUKS2 header with a specified --offset larger than + the LUKS2 header size, do not create a larger file than needed. + +* Fix unspecified sector size for BitLocker compatible mode. + + Some BitLocker devices can contain zeroed sector size in the header. + In this case, the 512-byte sector should be used. + The bug was introduced in version 2.3.3. + +* Fix reading key data size in metadata for BitLocker compatible mode. + + Such devices with an unexpected entry in metadata can now be activated. + + Thanks to all users reporting these problems, BitLocker metadata documentation + is not publicly available, and we depend only on these reports. + +* Fix typos in documentation. diff --git a/docs/v2.3.5-ReleaseNotes b/docs/v2.3.5-ReleaseNotes new file mode 100644 index 0000000..bad4fdf --- /dev/null +++ b/docs/v2.3.5-ReleaseNotes @@ -0,0 +1,181 @@ +Cryptsetup 2.3.5 Release Notes +============================== +Stable bug-fix release with minor extensions. + +All users of cryptsetup 2.x and later should upgrade to this version. + +Changes since version 2.3.4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix partial reads of passphrase from an interactive terminal. + Some stable kernels (5.3.11) started to return buffer from a terminal + in parts of maximal size 64 bytes. + This breaks the reading of passphrases longer than 64 characters + entered through an interactive terminal. The change is already fixed + in later kernel releases, but tools now support such partial read from + terminal properly. + +* Fix maximal length of password entered through a terminal. + Now the maximal interactive passphrase length is exactly + 512 characters (not 511). + +* integritysetup: support new dm-integrity HMAC recalculation options. + + In older kernels (since version 4.19), an attacker can force + an automatic recalculation of integrity tags by modifying + the dm-integrity superblock. + This is a problem with a keyed algorithms (HMAC), where it expects + nobody can trigger such recalculation without the key. + (Automatic recalculation will start after the next activation.) + + Note that dm-integrity in standalone mode was *not* supposed + to provide cryptographic data integrity protection. + Despite that, we try to keep the system secure if keyed algorithms + are used. + Thank Daniel Glöckner for the original report of this problem. + + Authenticated encryption that provides data integrity protection (in + combination with dm-crypt and LUKS2) is not affected by this problem. + + The fix in the kernel for this problem contains two parts. + + Firstly, the dm-integrity kernel module disables integrity + recalculation if keyed algorithms (HMAC) are used. + This change is included in long-term stable kernels. + + Secondly, since the kernel version 5.11, dm-integrity introduces + modified protection where a journal-integrity algorithm guards + superblock; also, journal sections are protected. An attacker cannot + copy sectors from one journal section to another, and the superblock + also contains salt to prevent header replacement from another device. + + If you want to protect data with HMAC, you should always also use HMAC + for --journal-integrity. Keys can be independent. + If HMAC is used for data but not for the journal, the recalculation + option is disabled. + + If you need to use (insecure) backward compatibility implementation, + two new integritysetup options are introduced: + - Use --integrity-legacy-recalc (instead of --integrity-recalc) + to allow recalculation on legacy devices. + - Use --integrity-legacy-hmac in format action to force old insecure + HMAC format. + + Libcryptsetup API also introduces flags + CRYPT_COMPAT_LEGACY_INTEGRITY_HMAC and + CRYPT_COMPAT_LEGACY_INTEGRITY_RECALC + to set these through crypt_set_compatibility() call. + +* integritysetup: display of recalculating sector in dump command. + +* veritysetup: fix verity FEC if stored in the same image with hashes. + + Optional FEC (Forward Error Correction) data should cover the whole + data area, hashes (Merkle tree), and optionally additional metadata + (located after hash area). + + Unfortunately, if FEC data is stored in the same file as hash, + the calculation wrongly used the whole file size, thus overlaps with + the FEC area itself. This produced unusable and too large FEC data. + There is no problem if the FEC image is a separate image. + + The problem is now fixed, introducing FEC blocks calculation as: + - If the hash device is in a separate image, metadata covers the + whole rest of the image after the hash area. (Unchanged behavior.) + - If hash and FEC device is in the image, metadata ends on the FEC + area offset. + + Note: there is also a fix for FEC in the dm-verity kernel (on the way + to stable kernels) that fixes error correction with larger RS roots. + +* veritysetup: run FEC repair check even if root hash fails. + + Note: The userspace FEC verify command reports are only informational + for now. Code does not check verity hash after FEC recovery in + userspace. The Reed-Solomon decoder can then report the possibility + that it fixed data even if parity is too damaged. + This will be fixed in the next major release. + +* veritysetup: do not process hash image if hash area is empty. + + Sometimes the device is so small that there is only a root hash + needed, and the hash area is not used. + Also, the size of the hash image is not increased for hash block + alignment in this case. + +* veritysetup: store verity hash algorithm in superblock in lowercase. + + Otherwise, the kernel could refuse the activation of the device. + +* bitlk: fix a crash if the device disappears during BitLocker scan. + +* bitlk: show a better error when trying to open an NTFS device. + + Both BitLocker version 1 and NTFS have the same signature. + If a user opens an NTFS device without BitLocker, it now correctly + informs that it is not a BITLK device. + +* bitlk: add support for startup key protected VMKs. + + The startup key can be provided in --key-file option for open command. + +* Fix LUKS1 repair code (regression since version 1.7.x). + + We cannot trust possibly broken keyslots metadata in repair, so the + code recalculates them instead. + This makes the repair code working again when the master boot record + signature overwrites the LUKS header. + +* Fix luksKeyChange for LUKS2 with assigned tokens. + + The token references are now correctly assigned to the new keyslot + number. + +* Fix cryptsetup resize using LUKS2 tokens. + + Code needlessly asked for passphrase even though volume key was + already unlocked via LUKS2 token. + +* Print a visible error if device resize is not supported. + +* Add error message when suspending wrong non-LUKS device. + +* Fix default XTS mode key size in reencryption. + + The same luksFormat logic (double key size because XTS uses two keys) + is applied in the reencryption code. + +* Rephrase missing locking directory warning and move it to debug level. + + The system should later provide a safe transition to tempdir + configuration, so creating locking directory inside libcryptsetup + call is safe. + +* Many fixes for the use of cipher_null (empty debug cipher). + + Support for this empty cipher was intended as a debug feature and for + measuring performance overhead. Unfortunately, many systems started to + use it as an "empty shell" for LUKS (to enable encryption later). + + This use is very dangerous and it creates a false sense of security. + + Anyway, to not break such systems, we try to support these + configurations. + Using cipher_null in any production system is strongly discouraged! + + Fixes include: + - allow LUKS resume for a device with cipher_null. + - do not upload key in keyring when data cipher is null. + - switch to default cipher when reencrypting cipher_null device. + - replace possible bogus cipher_null keyslots before reencryption. + - fix broken detection of null cipher in LUKS2. + cipher_null is no longer possible to be used in keyslot encryption + in LUKS2, it can be used only for data for debugging purposes. + +* Fixes for libpasswdqc 2.0.x (optional passphrase quality check). + +* Fixes for problems discovered by various tools for code analysis. + + Fixes include a rework of libpopt command line option string leaks. + +* Various fixes to man pages. diff --git a/docs/v2.3.6-ReleaseNotes b/docs/v2.3.6-ReleaseNotes new file mode 100644 index 0000000..deb975e --- /dev/null +++ b/docs/v2.3.6-ReleaseNotes @@ -0,0 +1,56 @@ +Cryptsetup 2.3.6 Release Notes +============================== +Stable bug-fix release with minor extensions. + +All users of cryptsetup 2.x and later should upgrade to this version. + +Changes since version 2.3.5 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* integritysetup: Fix possible dm-integrity mapping table truncation. + + While integritysetup in standalone mode (no encryption) was not + designed to provide keyed (and cryptographically strong) data + integrity protection, some options can use such algorithms (HMAC). + + If a key is used, it is directly sent to the kernel dm-integrity as + a mapping table option (no key derivation is performed). + For HMAC, such a key could be quite long (up to 4096 bytes in + integritysetup CLI). + + Unfortunately, due to fixed buffers and not correctly checking string + truncation, some parameter combinations could cause truncation + of the dm-integrity mapping table. + In most cases, the table was rejected by the kernel. + The worst possible case was key truncation for HMAC options + (internal_hash and journal_mac dm-integrity table options). + + This release fixes possible truncation and also adds more sanity + checks to reject truncated options. + Also, integritysetup now mentions maximal allowed key size + in --help output. + + For old standalone dm-integrity devices where the key length was + truncated, you have to modify (shorten) --integrity-key-size + resp. --journal-integrity-key-size option now. + + This bug is _not_ present for dm-crypt/LUKS, LUKS2 (including + integrity protection), or dm-verity devices; it affects only + standalone dm-integrity with HMAC integrity protection. + +* cryptsetup: Backup header can be used to activate TCRYPT device. + Use --header option to specify the header. + +* cryptsetup: Avoid LUKS2 decryption without detached header. + This feature will be added later and is currently not supported. + +* Additional fixes and workarounds for common warnings produced + by some static analysis tools (like gcc-11 analyzer) and additional + code hardening. + +* Fix standalone libintl detection for compiled tests. + +* Add Blake2b and Blake2s hash support for crypto backends. + Kernel and gcrypt crypto backend support all variants. + OpenSSL supports only Blake2b-512 and Blake2s-256. + Crypto backend supports kernel notation e.g. "blake2b-512". diff --git a/docs/v2.4.0-ReleaseNotes b/docs/v2.4.0-ReleaseNotes new file mode 100644 index 0000000..2d70e0a --- /dev/null +++ b/docs/v2.4.0-ReleaseNotes @@ -0,0 +1,302 @@ +Cryptsetup 2.4.0 Release Notes +============================== +Stable release with new features and bug fixes. + +This version introduces support for external libraries +(plugins) for handling LUKS2 token objects. + +Changes since version 2.3.6 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* External LUKS token plugins + + A LUKS2 token is an object that can describe how to get a passphrase + to unlock a particular keyslot. The generic metadata format is part + of the LUKS2 specification. + + Cryptsetup 2.4 adds the possibility to implement token handlers + in external libraries (possibly provided by other projects). + + A token library allows cryptsetup to understand metadata and provide + basic operations. Currently external tokens may be used to unlock + keyslots for following CLI actions: open (luksOpen), + refresh (open --refresh), resize and dump (prints token specific + content). + + LUKS2 devices cannot be resumed (luksResume action) via tokens yet. + Support for resume and other actions will be added later. + + The library now provides an interface that automatically tries to load + an external library for a token object in LUKS2 metadata. + + Token libraries should be installed in the cryptsetup subdirectory + (usually /lib*/cryptsetup). This path is configurable through + --with-luks2-external-tokens-path configure option. + + The external plugin loading can be compiled entirely out if + --disable-external-tokens configure option is used. The external token + interface can also be disabled runtime on the command line by + --disable-external-tokens cryptsetup switch or by calling + crypt_token_external_disable() API function. + + The name of the loaded token library is determined from the JSON LUKS + metadata token object type. For example, "ssh" token will load library + "libcryptsetup-token-ssh.so". + + External projects can use this interface to handle specific hardware + without introducing additional dependencies to libcryptsetup core. + + As of cryptsetup 2.4.0 release systemd project already merged upstream + native cryptsetup token handler for its systemd-tpm2 LUKS2 token + released originally in systemd-v248. The token can be created using + systemd-cryptenroll utility and devices may be manipulated either by + systemd-cryptsetup cli or by cryptsetup for actions listed above. + + Other tokens like systemd-fido2 and systemd-pkcs11 are currently + in-review. + +* Experimental SSH token + + As a demonstration of the external LUKS2 token interface, a new SSH + token handler and cryptsetup-ssh utility is now provided and compiled + by default. + + Crypsetup SSH token allows using remote keyfile through SSH protocol + (it will authenticate through SSH certificates). + + You can disable the build of this token library with + --disable-ssh-token configure option. + +To configure the token metadata, you need cryptsetup-ssh utility. + +Activation of the device is then performed by the cryptsetup utility. + +Example (how to activate LUKS2 through remote keyfile): + + - configure existing LUKS2 device with keyslot activated by a keyfile + # cryptsetup luksAddKey keyfile --key-slot 2 + + - store that keyfile on a remote system accessible through SSH + + - configure SSH to use certificate for authentication + + - add a LUKS2 token with cryptsetup-ssh utility: + # cryptsetup-ssh add 1 --key-slot 2 \ + --ssh-server test-vm \ + --ssh-user test \ + --ssh-path /home/test/keyfile \ + --ssh-keypath /home/test/.ssh/test_rsa_key + + - you should see token metadata now with "cryptsetup luksDump ..." + ... + Tokens: + 0: ssh + ssh_server: test-vm + ssh_user: test + ssh_path: /home/test/keyfile + ssh_key_path: /home/test/.ssh/test_rsa_key + Keyslot: 2 + + + - activation now should be automatic + # cryptsetup open test --verbose + SSH token initiating ssh session. + Key slot 2 unlocked. + Command successful. + + - to remove a token, you can use "cryptsetup token remove" command + (no plugin library required) + + Please note SSH token is just demonstration of plugin interface API, + it is an EXPERIMENTAL feature. + +* Add cryptsetup --token-type parameter. + + It restricts token type to the parameter value in case no specific + token-id is selected. + +* Support for token based activation with PIN. + + If specific token requires PIN to unlock keyslot passphrase and + --token-only parameter was used cryptsetup asks for additional + token PIN. + +* Respect keyslot priority with token-based activation. + +* Default LUKS2 PBKDF is now Argon2id + + Cryptsetup LUKS2 was using Argon2 while there were two versions, + data-independent (Argon2i) suitable for the KDF use case and + Argon2d (data-dependent). Later Argon2id was introduced as a new + mandatory algorithm. + + We switched the password-based key derivation algorithms + following the latest version of Argon2 RFC draft + (https://datatracker.ietf.org/doc/draft-irtf-cfrg-argon2/) to Argon2id + (from Argon2i) as it is the mandatory and primary version + of the Argon2 algorithm. + + There is no need to modify older containers; the main reason is that + RFC makes Argon2id the primary variant, while Argon2i subvariant is + only optional. + Argon2id provides better protection to side-channel attacks while + still providing protection to time-memory tradeoffs. + + We will switch to OpenSSL implementation once it is available. + With a crystal ball as a reference, it could happen early in + OpenSSL 3.1 release. + Watch https://github.com/openssl/openssl/issues/4091. + +* Increase minimal memory cost for Argon2 benchmark to 64MiB. + + This patch increases the benchmarking value to 64 MiB (as minimal + suggested values in Argon2 RFC). For compatibility reasons, we still + allow older limits if set by a parameter. + + NOTE: Argon2 RFC draft defines suggested parameters for disk + encryption, but the LUKS2 approach is slightly different. We need to + provide platform-independent values. The values in the draft expect + 64bit systems (suggesting using 6 GiB of RAM). In comparison, we need + to provide compatibility with all 32bit systems, so allocating more + than 4GiB memory is not an option for LUKS2. + + The maximal limit in LUKS2 stays for 4 GiB, and by default LUKS2 PBKDF + benchmarking sets maximum to 1 GIB, preferring an increase of CPU cost + while running benchmark + +* Autodetect optimal encryption sector size on LUKS2 format. + + While the support for larger encryption sectors is supported + for several releases, it required an additional parameter. + + Code now uses automatic detection of 4096-bytes native sector devices + and automatically enables 4096-bytes encryption size for LUKS2. + + If no setor size option is used, sector size is detected + automatically by cryptsetup. For libcryptsetup API, autodetection + happens once you specify sector_size to 0. + + NOTE: crypt_format() function runs autodetection ONLY if you + recompile your application to the new API symbol version. + For backward compatibility, older applications ignore this parameter. + +* Use VeraCrypt option by default and add --disable-veracrypt option. + + While TrueCrypt is no longer developed and supported since 2014, + VeraCrypt devices (a successor of TrueCrypt) are much more used today. + + Default is now to support VeraCrypt format (in addition to TrueCrypt), + making the --veracrypt option obsolete (ignored as it is the default). + + If you need to disable VeraCrypt support, use the new option + --disable-veracrypt. + + This option increases the time to recognize wrong passwords because + some VeraCrypt modes use a high PBKDF2 iteration count, and the code + must try all variants. This could be limited by using --hash and + --cipher options mentioned below. + +* Support --hash and --cipher to limit opening time for TCRYPT type + + If a user knows which particular PBKDF2 hash or cipher is used for + TrueCrypt/VeraCrypt container, TCRYPT format now supports --hash and + --cipher option. + + Note the value means substring (all cipher chains containing + the cipher substring are tried). + + For example, you can use + # cryptsetup tcryptDump --hash sha512 + + Note: to speed up the scan, the hash option (used for PBKDF)2 matters. + Cipher variants are scanned very quickly. + + Use with care. + It can reveal some sensitive attributes of the container! + +* Fixed default OpenSSL crypt backend support for OpenSSL3. + + For OpenSSL version 3, we need to load legacy provider for older hash + and ciphers. For example, RIPEMD160 and Whirlpool hash algorithms are + no longer available by default. + + NOTE: the plain format still uses RIPEMD160 for password hashing by + default. Changing the default would cause incompatibilities for many + old systems. Nevertheless, such a change will be needed very soon. + +* integritysetup: add integrity-recalculate-reset flag. + + The new dm-integrity option in kernel 5.13 can restart recalculation + from the beginning of the device. + It can be used to change the integrity checksum function. + + New integritysetup --integrity-recalculate-reset option is added to + integritysetup, and CRYPT_ACTIVATE_RECALCULATE_RESET flag to API. + +* cryptsetup: retains keyslot number in luksChangeKey for LUKS2. + + In LUKS1, any change in keyslot means keyslot number change. + + In LUKS2, we can retain the keyslot number. + Now luksKeyChange and crypt_keyslot_change_by_passphrase() API + retains keyslot number for LUKS2 by default. + +* Fix cryptsetup resize using LUKS2 tokens. + + Fix a bug where cryptsetup needlessly asked for a passphrase even + though the volume key was already unlocked via LUKS2 token. + +* Add close --deferred and --cancel-deferred options. + + All command-line utilities now understand deferred options for the + close command. Deferred close means that the device is removed + automagically after the last user closed the device. + Cancel deferred means to cancel this operation (so the device remains + active even if there a no longer active users). + + CRYPT_DEACTIVATE_DEFERRED and CRYPT_DEACTIVATE_DEFERRED_CANCEL flags + are now available for API. + +* Rewritten command-line option parsing to avoid libpopt arguments + memory leaks. + + Note: some distributions use patched lipopt that still leaks memory + inside internal code (see Debian bug 941814). + +* Add --test-args option. + + New --test-args option can be used for syntax checking for valid + command-line arguments with no actions performed. + Note that it cannot detect unknown algorithm names and similar where + we need call API functions. + +* veritysetup: add --root-hash-file option + Allow passing the root hash via a file, rather than verbatim on + the command line, for the open, verify, and format actions. + +* libcryptsetup C API extensions (see libcryptsetup.h for details) + + - crypt_logf - a printf like log function + - crypt_dump_json - dump LUKS2 metadata in JSON format + - crypt_header_is_detached - check if context use detached header + - crypt_token_max - get maximal tokens number + - crypt_token_external_path - get path for plugins (or NULL) + - crypt_token_external_disable - disable runtime support for plugins + - crypt_activate_by_token_pin - activate by token with additional PIN + - crypt_reencrypt_run - fixed API for deprecated crypt_reencrypt + + The token plugin library interface cosists from these versioned + exported symbols (for details see header file and SSH token example): + cryptsetup_token_open + cryptsetup_token_open_pin + cryptsetup_token_buffer_free + cryptsetup_token_validate + cryptsetup_token_dump + cryptsetup_token_version + + Since version 2.4 libcryptsetup uses exact symbol versioning + Newly introduced functions have CRYPTSETUP_2.4 namespace (the old + symbol always used CRYPTSETUP_2.0). + There is no change in soname (the library is backward compatible). + + * Many fixes and additions to documentation and man pages. diff --git a/docs/v2.4.1-ReleaseNotes b/docs/v2.4.1-ReleaseNotes new file mode 100644 index 0000000..7aac27d --- /dev/null +++ b/docs/v2.4.1-ReleaseNotes @@ -0,0 +1,47 @@ +Cryptsetup 2.4.1 Release Notes +============================== +Stable bug-fix release with minor extensions. + +All users of cryptsetup 2.4.0 should upgrade to this version. + +Changes since version 2.4.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix compilation for libc implementations without dlvsym(). + + Some alternative libc implementations (like musl) do not provide + versioned symbols dlvsym function. Code now fallbacks to dlsym + operation for dynamic LUKS2 token load. + It is up to maintainers to ensure that LUKS2 token plugins are + compiled for the supported version. + +* Fix compilation and tests on systems with non-standard libraries + (standalone argp library, external gettext library, BusyBox + implementations of standard tools). + +* Try to workaround some issues on systems without udev support. + NOTE: non-udev systems cannot provide all functionality for kernel + device-mapper, and some operations can fail. + +* Fixes for OpenSSL3 crypto backend (including FIPS mode). + Because cryptsetup still requires some hash functions implemented + in OpenSSL3 legacy provider, crypto backend now uses its library + context and tries to load both default and legacy OpenSSL3 providers. + + If FIPS mode is detected, no library context is used, and it is up + to the OpenSSL system-wide policy to load proper providers. + + NOTE: We still use some deprecated API in the OpenSSL3 backend, + and there are some known problems in OpenSSL 3.0.0. + +* Print error message when assigning a token to an inactive keyslot. + +* Fix offset bug in LUKS2 encryption code if --offset option was used. + +* Do not allow LUKS2 decryption for devices with data offset. + Such devices cannot be used after decryption. + +* Fix LUKS1 cryptsetup repair command for some specific problems. + Repair code can now fix wrongly used initialization vector + specification in ECB mode (that is insecure anyway!) and repair + the upper-case hash specification in the LUKS1 header. diff --git a/docs/v2.4.2-ReleaseNotes b/docs/v2.4.2-ReleaseNotes new file mode 100644 index 0000000..3c40011 --- /dev/null +++ b/docs/v2.4.2-ReleaseNotes @@ -0,0 +1,37 @@ +Cryptsetup 2.4.2 Release Notes +============================== +Stable bug-fix release. + +All users of cryptsetup 2.4.1 should upgrade to this version. + +Changes since version 2.4.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix possible large memory allocation if LUKS2 header size is invalid. + LUKS2 code read the full header to buffer to verify the checksum. + The maximal supported header size now limits the memory allocation. + +* Fix memory corruption in debug message printing LUKS2 checksum. + +* veritysetup: remove link to the UUID library for the static build. + +* Remove link to pwquality library for integritysetup and veritysetup. + These tools do not read passphrases. + +* OpenSSL3 backend: avoid remaining deprecated calls in API. + Crypto backend no longer use API deprecated in OpenSSL 3.0 + + +* Check if kernel device-mapper create device failed in an early phase. + This happens when a concurrent creation of device-mapper devices + meets in the very early state. + +* Do not set compiler optimization flag for Argon2 KDF if the memory + wipe is implemented in libc. + +* Do not attempt to unload LUKS2 tokens if external tokens are disabled. + This allows building a static binary with --disable-external-tokens. + +* LUKS convert: also check sysfs for device activity. + If udev symlink is missing, code fallbacks to sysfs scan to prevent + data corruption for the active device. diff --git a/docs/v2.4.3-ReleaseNotes b/docs/v2.4.3-ReleaseNotes new file mode 100644 index 0000000..d1b6178 --- /dev/null +++ b/docs/v2.4.3-ReleaseNotes @@ -0,0 +1,101 @@ +Cryptsetup 2.4.3 Release Notes +============================== +Stable security bug-fix release that fixes CVE-2021-4122. + +All users of cryptsetup 2.4.x must upgrade to this version. + +Changes since version 2.4.2 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Fix possible attacks against data confidentiality through LUKS2 online + reencryption extension crash recovery (CVE-2021-4122). + + An attacker can modify on-disk metadata to simulate decryption in + progress with crashed (unfinished) reencryption step and persistently + decrypt part of the LUKS device. + + This attack requires repeated physical access to the LUKS device but + no knowledge of user passphrases. + + The decryption step is performed after a valid user activates + the device with a correct passphrase and modified metadata. + There are no visible warnings for the user that such recovery happened + (except using the luksDump command). The attack can also be reversed + afterward (simulating crashed encryption from a plaintext) with + possible modification of revealed plaintext. + + The size of possible decrypted data depends on configured LUKS2 header + size (metadata size is configurable for LUKS2). + With the default parameters (16 MiB LUKS2 header) and only one + allocated keyslot (512 bit key for AES-XTS), simulated decryption with + checksum resilience SHA1 (20 bytes checksum for 4096-byte blocks), + the maximal decrypted size can be over 3GiB. + + The attack is not applicable to LUKS1 format, but the attacker can + update metadata in place to LUKS2 format as an additional step. + For such a converted LUKS2 header, the keyslot area is limited to + decrypted size (with SHA1 checksums) over 300 MiB. + + The issue is present in all cryptsetup releases since 2.2.0. + Versions 1.x, 2.0.x, and 2.1.x are not affected, as these do not + contain LUKS2 reencryption extension. + + The problem was caused by reusing a mechanism designed for actual + reencryption operation without reassessing the security impact for new + encryption and decryption operations. While the reencryption requires + calculating and verifying both key digests, no digest was needed to + initiate decryption recovery if the destination is plaintext (no + encryption key). Also, some metadata (like encryption cipher) is not + protected, and an attacker could change it. Note that LUKS2 protects + visible metadata only when a random change occurs. It does not protect + against intentional modification but such modification must not cause + a violation of data confidentiality. + + The fix introduces additional digest protection of reencryption + metadata. The digest is calculated from known keys and critical + reencryption metadata. Now an attacker cannot create correct metadata + digest without knowledge of a passphrase for used keyslots. + For more details, see LUKS2 On-Disk Format Specification version 1.1.0. + + The former reencryption operation (without the additional digest) is no + longer supported (reencryption with the digest is not backward + compatible). You need to finish in-progress reencryption before + updating to new packages. The alternative approach is to perform + a repair command from the updated package to recalculate reencryption + digest and fix metadata. + The reencryption repair operation always require a user passphrase. + + WARNING: Devices with older reencryption in progress can be no longer + activated without performing the action mentioned above. + + Encryption in progress can be detected by running the luksDump command + (output includes reencrypt keyslot with reencryption parameters). Also, + during the active reencryption, no keyslot operations are available + (change of passphrases, etc.). + + The issue was found by Milan Broz as cryptsetup maintainer. + +Other changes +~~~~~~~~~~~~~ +* Add configure option --disable-luks2-reencryption to completely disable + LUKS2 reencryption code. + + When used, the libcryptsetup library can read metadata with + reencryption code, but all reencryption API calls and cryptsetup + reencrypt commands are disabled. + + Devices with online reencryption in progress cannot be activated. + This option can cause some incompatibilities. Please use with care. + +* Improve internal metadata validation code for reencryption metadata. + +* Add updated documentation for LUKS2 On-Disk Format Specification + version 1.1.0 (with reencryption extension description and updated + metadata description). See docs/on-disk-format-luks2.pdf or online + version in https://gitlab.com/cryptsetup/LUKS2-docs repository. + +* Fix support for bitlk (BitLocker compatible) startup key with new + metadata entry introduced in Windows 11. + +* Fix space restriction for LUKS2 reencryption with data shift. + The code required more space than was needed. diff --git a/docs/v2.5.0-ReleaseNotes b/docs/v2.5.0-ReleaseNotes new file mode 100644 index 0000000..f5bdeec --- /dev/null +++ b/docs/v2.5.0-ReleaseNotes @@ -0,0 +1,291 @@ +Cryptsetup 2.5.0 Release Notes +============================== +Stable release with new features and bug fixes. + +Changes since version 2.4.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Split manual pages into per-action pages and use AsciiDoc format. + + Manual pages are now generated from AsciiDoc format, allowing easy + conditional modifications for per-action options. + + Generation of man pages requires the asciidoctor tool installed. + + Pre-generated man pages are also included in the distribution tarball. + You can use --disable-asciidoc configure option to skip man page + generation completely. In this case, pre-generated man pages will be + used for installation. + + For cryptsetup, there is main man page (cryptsetup.8) that references + separate man pages for each command (for example, cryptsetup-open.8). + You can open such a man page by simply running "man cryptsetup open". + Also, man pages for action aliases are available (cryptsetup-luksOpen.8 + is an alias for cryptsetup-open.8, etc.) + +LUKS volume reencryption changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Remove cryptsetup-reencrypt tool from the project and move reencryption + to already existing "cryptsetup reencrypt" command. + + Cryptsetup reencrypt now handles both LUKS1 and LUKS2 reencryption, + encryption, and decryption. + + If you need to emulate the old cryptsetup-reencrypt binary, use simple + wrappers script running "exec cryptsetup reencrypt $@". + + All command line options should be compatible. An exception is the + reencryption of LUKS2 volumes with old LUKS1 reencryption code that was + replaced by native and more resilient LUKS2 reencryption. + +* LUKS2: implement --decryption option that allows LUKS removal. The + operation can run online or offline and supports the data shift option. + + During the initialization, the LUKS2 header is exported to a file. + The first data segment is moved to the head of the data device in place + of the original header. + + The feature internally introduces several new resilience modes + (combination of existing modes datashift and "checksum" or "journal"). + Datashift resilience mode is applied for data moved towards the first + segment, and the first segment is then decrypted in place. + + This decryption mode is not backward compatible with prior LUKS2 + reencryption. Interrupted operations in progress cannot be resumed + using older cryptsetup releases. + +* Reencryption metadata options that are not compatible with recent code + (features implemented in more recent releases) are now only read, but + code will not activate or modify such metadata. + Reencryption metadata contains a version that is validated when + reencryption is resumed. + For more info, see the updated LUKS2 on-disk format specification. + + Safe operation of reencryption is to always finish the operation with + only one version of the tools. + +* Fix decryption operation with --active-name option and restrict + it to be used only with LUKS2. + +* Do not refresh reencryption digest when not needed. + This should speed up the reencryption resume process. + +* Store proper resilience data in LUKS2 reencrypt initialization. + Resuming reencryption now does not require specification of resilience + type parameters if these are the same as during initialization. + +* Properly wipe the unused area after reencryption with datashift in + the forward direction. + +* Check datashift value against larger sector size. + For example, it could cause an issue if misaligned 4K sector appears + during decryption. + +* Do not allow sector size increase reencryption in offline mode. + The eventual logical block size increase on the dm-crypt device above + may lead to an unusable filesystem. Do not allow offline reencryption + when sector size increase is requested. + + You can use --force-offline-reencrypt option to override this check + (and potentially destroy the data). + +* Do not allow dangerous sector size change during reencryption. + By changing the encryption sector size during reencryption, a user + may increase the effective logical block size for the dm-crypt active + device. + + Do not allow encryption sector size to be increased over the value + provided by fs superblock in BLOCK_SIZE property. + +* Ask the user for confirmation before resuming reencryption. + The prompt is not shown in batch mode or when the user explicitly asks + for a reencryption resume via --resume-only. + +* Do not resume reencryption with conflicting parameters. + For example, if the operation was initialized as --encrypt, do not + allow resume with opposing parameter --decrypt and vice versa. + Also, the code now checks for conflicting resilience parameters + (datashift cannot be changed after initialization). + +* Add --force-offline-reencrypt option. + It can be used to enforce offline reencryption in batch mode when + the device is a regular file; therefore, cryptsetup cannot detect + properly active devices using it. + Also, it may be useful to override the active device auto-detection + for specific storage configurations (dangerous!). + +* Do not allow nested encryption in LUKS reencrypt. + Avoid accidental nested encryption via cryptsetup reencrypt --encrypt. + +* Fix --test-passphrase when the device is in reencryption. + +* Do not upload keys in keyring during offline reencryption. + Reencryption runs in userspace, so the kernel does not need the key. + +* Support all options allowed with luksFormat with encrypt action. + +* Add prompt if LUKS2 decryption is run with a detached header. + +* Add warning for reencryption of file image and mention + the possible use of --force-offline-reencrypt option. + +Other changes +~~~~~~~~~~~~~ + +* Add resize action to integritysetup. + This allows resizing of standalone integrity devices. + +* Support --device-size option (that allows unit specification) for plain + devices (existing --size option requires 512-byte sectors units). + +* Fix detection of encryption sector size if a detached header is used. + +* Remove obsolete dracut plugin reencryption example. + +* Fix possible keyslot area size overflow during conversion to LUKS2. + If keyslots are not sorted according to binary area offset, the area + size calculation was wrong and could overflow. + +* Hardening and fixes to LUKS2 validation functions: + + * Log a visible error if convert fails due to validation check. + + * Check for interval (keyslot and segment area) overflow. + + * Check cipher availability before LUKS conversion to LUKS2. + Some historic incompatibilities are ignored for LUKS1 but do not + work for LUKS2. + + * Add empty string check to LUKS2 metadata JSON validation. + Most of the LUKS2 fields cannot be empty. + + * Fix JSON objects validation to check JSON object type properly. + +* TCRYPT: Properly apply retry count and continue if some PBKDF variant + is unavailable. + +* BITLK: Add a warning when activating a device with the wrong size + stored in metadata. + +* BITLK: Add BitLocker volume size to dump command. + +* BITLK: Fix possible UTF16 buffer overflow in volume key dump. + +* BITLK: Skip question if the batch mode is set for volume key dump. + +* BITLK: Check dm-zero availability in the kernel. + Bitlocker compatible mode uses dm-zero to mask metadata area. + The device cannot be activated if dm-zero is not available. + +* Fix error message for LUKS2-only cryptsetup commands to explicitly + state LUKS2 version is required. + +* Fix error message for incompatible dm-integrity metadata. + If the integritysetup tool is too old, kernel dm-integrity may use + a more recent version of dm-integrity metadata. + +* Properly deactivate the integrity device even if the LUKS2 header + is no longer available. + If LUKS2 is used with integrity protection, there is always + a dm-integrity device underneath that must be deactivated. + +* Allow use of --header option for cryptsetup close. + This can be used to check that the activated device has the same UUID. + +* Fix activation of LUKS2 device with integrity and detached header. + The kernel-parsed dm-integrity superblock is always located on the + data device, the incorrectly used detached header device here. + +* Add ZEROOUT IOCTL support for crypt_wipe API call. + For block devices, we can use optimized in-kernel BLKZEROOUT ioctl. + +* VERITY: set loopback sector size according to dm-verity block sizes. + Verity block size has the same limits, so we can optimize the loop + device to increase performance. + +* Other Documentation and man page improvements: + + * Update LUKS2 on-disk format description. + + * Add per-keyslot LUKS2 options to the man page. + Some options were missing for LUKS2 luksAddKey and luksChangeKey. + + * Fix cryptsetup manpage to use PBKDF consistently. + + * Add compile info to README. This information was lost when we removed + the default automake INSTALL file. + + * Use volume key consistently in FAQ and man pages. + + * Use markdown version of FAQ directly for installation. + + * Clarify graceful reencryption interruption. + Currently, it can be interrupted by both SIGINT and SIGTERM signals. + + * Add new mailing list info. + + * Mention non-cryptographic xxhash64 hash for integrity protection. + +* veritysetup: dump device sizes. + Calculating device sizes for verity devices is a little bit tricky. + Data, hash, and FEC can share devices or be separate devices. + Now dump command prints used device sizes, but it requires that + the user specifies all values that are not stored in superblock + (like FEC device and FEC roots). + +* Fix check for argp_usage in configure if argp-standalone lib is used. + +* Add constant time memcmp and hexa print implementation and use it for + cryptographic keys handling. + +* Display progress when wiping the end of the resized device. + +* LUKS2 token: prefer token PIN query before passphrase in some cases. + When a user provides --token-type or specific --token-id, a token PIN + query is preferred to a passphrase query. + +* LUKS2 token: allow tokens to be replaced with --token-replace option + for cryptsetup token command. + +* LUKS2 token: do not continue operation when interrupted in PIN prompt. + +* Add --progress-json parameter to utilities. + Progress data can now be printed out in JSON format suitable for + machine processing. + +* Embedded Argon2 PBKDF: optimize and simplify thread exit. + +* Avoid using SHA1 in tests and fix new enforcements introduced in FIPS + provider for OpenSSL3 (like minimal parameters for PBKDF2). + +* Use custom UTF conversion and avoid linking to iconv as a dependency. + +* Reimplement BASE64 with simplified code instead of coreutils version. + +* Fix regression when warning messages were not displayed + if some kernel feature is not supported (2.4.2). + +* Add support for --key-slot option in luksResume action. + +Libcryptsetup API extensions and changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Properly define uint32_t constants in API. + This is not a real change, but it avoids strict compiler warnings. + +* crypt_resume_by_token_pin() - Resume crypt device using LUKS2 token. + +* crypt_get_label() - Get the label of the LUKS2 device. + +* crypt_get_subsystem() - Get the subsystem label of the LUKS2 device. + +* Make CRYPT_WIPE_ENCRYPTED_ZERO crypt_wipe() option obsolete. + It was never implemented (the idea was to speed up wipe), but with + the recent RNG performance changes, it makes no longer sense. + +* Add struct crypt_params_reencrypt changes related to decryption. + +* Improve crypt_reencrypt_status() return values. + Empty or any non-LUKS types now returns CRYPT_REENCRYPT_INVALID status. + For LUKS1 devices, it returns CRYPT_REENCRYPT_NONE. diff --git a/docs/v2.6.0-ReleaseNotes b/docs/v2.6.0-ReleaseNotes new file mode 100644 index 0000000..6303945 --- /dev/null +++ b/docs/v2.6.0-ReleaseNotes @@ -0,0 +1,236 @@ +Cryptsetup 2.6.0 Release Notes +============================== +Stable release with new features and bug fixes. + +Changes since version 2.5.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Introduce support for handling macOS FileVault2 devices (FVAULT2). + + Cryptsetup now supports the mapping of FileVault2 full-disk encryption + by Apple for the macOS operating system using a native Linux kernel. + You can open an existing USB FileVault portable device and (with + the hfsplus filesystem driver) access the native data read/write. + + Cryptsetup supports only (legacy) FileVault2 based on Core Storage + and HFS+ filesystem (introduced in MacOS X 10.7 Lion). + It does NOT support the new version of FileVault based on the APFS + filesystem used in recent macOS versions. + + Header formatting and changes are not supported; cryptsetup never + changes the metadata on the device. + + FVAULT2 extension requires kernel userspace crypto API and kernel + driver for HFS+ (hfsplus) filesystem (available on most systems today). + + Example of using FileVault2 formatted USB device: + + A typical encrypted device contains three partitions; the FileVault + encrypted partition is here sda2: + + $ lsblk -o NAME,FSTYPE,LABEL /dev/sda + NAME FSTYPE LABEL + sda + |-sda1 vfat EFI + |-sda2 + `-sda3 hfsplus Boot OS X + + Note: blkid does not recognize FileVault2 format yet. + + To dump metadata information about the device, you can use + the fvault2Dump command: + + $ cryptsetup fvault2Dump /dev/sda2 + Header information for FVAULT2 device /dev/sda2. + Physical volume UUID: 6f353c05-daae-4e76-a0ee-6a9569a22d81 + Family UUID: f82cceb0-a788-4815-945a-53d57fcd55a8 + Logical volume offset: 67108864 [bytes] + Logical volume size: 3288334336 [bytes] + Cipher: aes + Cipher mode: xts-plain64 + PBKDF2 iterations: 97962 + PBKDF2 salt: 173a4ec7447662ec79ca7a47df6c2a01 + + To activate the device, use open --type fvault2 option: + + $ cryptsetup open --type fvault2 /dev/sda2 test + Enter passphrase for /dev/sda2: ... + + And check the status of the active device: + + $ cryptsetup status test + /dev/mapper/test is active. + type: FVAULT2 + cipher: aes-xts-plain64 + keysize: 256 bits + key location: dm-crypt + device: /dev/sda2 + sector size: 512 + offset: 131072 sectors + size: 6422528 sectors + mode: read/write + + Now, if the kernel contains hfsplus filesystem driver, you can mount + decrypted content: + + $ mount /dev/mapper/test /mnt/test + + For more info about implementation, please refer to the master thesis + by Pavel Tobias, which was the source for this extension. + https://is.muni.cz/th/p0aok/?lang=en + +* libcryptsetup: no longer use global memory locking through mlockall() + + For many years, libcryptsetup locked all memory (including dependent + library address space) to prevent swapping sensitive content outside + of RAM. + + This strategy no longer works as the locking of basic libraries exceeds + the memory locking limit if running as a non-root user. + + Libcryptsetup now locks only memory ranges containing sensitive + material (keys) through crypt_safe_alloc() calls. + + This change solves many reported mysterious problems of unexpected + failures. If the initial lock was still under the limit and succeeded, + some following memory allocation could fail later as it exceeded + the locking limit. If the initial locking fails, memory locking + was quietly ignored completely. + + The whole crypt_memory_lock() API call is deprecated; it no longer + calls memlockall(). + +* libcryptsetup: process priority is increased only for key derivation + (PBKDF) calls. + + Increasing priority was tight to memory locking and works only if + running under superuser. + Only PBKDF calls and benchmarking now increase the process priority. + +* Add new LUKS keyslot context handling functions and API. + + In practice, the luksAddKey action does two operations. + It unlocks the existing device volume key and stores the unlocked + volume key in a new keyslot. + Previously the options were limited to key files and passphrases. + + Newly available methods (keyslot contexts) are passphrase, keyfile, + key (binary representation), and LUKS2 token. + + To unlock a keyslot user may: + - provide existing passphrase via interactive prompt (default method) + - use --key-file option to provide a file with a valid passphrase + - provide volume key directly via --volume-key-file + - unlock keyslot via all available LUKS2 tokens by --token-only + - unlock keyslot via specific token with --token-id + - unlock keyslot via specific token type by --token-type + + To provide the passphrase for a new keyslot, a user may: + - provide existing passphrase via interactive prompt (default method) + - use --new-keyfile to read the passphrase from the file + - use --new-token-id to select LUKS2 token to get passphrase + for new keyslot. The new keyslot is assigned to the selected token + id if the operation is successful. + +* The volume key may now be extracted using a passphrase, keyfile, or + token. For LUKS devices, it also returns the volume key after + a successful crypt_format call. + +* Fix --disable-luks2-reencryption configuration option. + +* cryptsetup: Print a better error message and warning if the format + produces an image without space available for data. + + Activation now fails early with a more descriptive message. + +* Print error if anti-forensic LUKS2 hash setting is not available. + If the specified hash was not available, activation quietly failed. + +* Fix internal crypt segment compare routine if the user + specified cipher in kernel format (capi: prefix). + +* cryptsetup: Add token unassign action. + + This action allows removing token binding on specific keyslot. + +* veritysetup: add support for --use-tasklets option. + + This option sets try_verify_in_tasklet kernel dm-verity option + (available since Linux kernel 6.0) to allow some performance + improvement on specific systems. + +* Provide pkgconfig Require.private settings. + + While we do not completely provide static build on udev systems, + it helps produce statically linked binaries in certain situations. + +* Always update automake library files if autogen.sh is run. + + For several releases, we distributed older automake scripts by mistake. + +* reencryption: Fix user defined moved segment size in LUKS2 decryption. + + The --hotzone-size argument was ignored in cases where the actual data + size was less than the original LUKS2 data offset. + +* Delegate FIPS mode detection to configured crypto backend. + System FIPS mode check no longer depends on /etc/system-fips file. + +* tests: externally provided systemd plugin is now optionally compiled + from systemd git and tested with cryptsetup + +* tests: initial integration to OSS-fuzz project with basic crypt_load() + test for LUKS2 and JSON mutated fuzzing. + + For more info, see README in tests/fuzz directory. + +* Update documentation, including FAQ and man pages. + +Libcryptsetup API extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The libcryptsetup API is backward compatible with existing symbols. + +New symbols: + crypt_keyslot_context_init_by_passphrase + crypt_keyslot_context_init_by_keyfile + crypt_keyslot_context_init_by_token + crypt_keyslot_context_init_by_volume_key + crypt_keyslot_context_get_error + crypt_keyslot_context_set_pin + crypt_keyslot_context_get_type + crypt_keyslot_context_free + crypt_keyslot_add_by_keyslot_context + crypt_volume_key_get_by_keyslot_context + +New defines: + CRYPT_FVAULT2 "FVAULT2" (FileVault2 compatible mode) + +Keyslot context types: + CRYPT_KC_TYPE_PASSPHRASE + CRYPT_KC_TYPE_KEYFILE + CRYPT_KC_TYPE_TOKEN + CRYPT_KC_TYPE_KEY + + CRYPT_ACTIVATE_TASKLETS (dm-verity: use tasklets activation flag) + +WARNING! +~~~~~~~~ +The next version of cryptsetup will change the encryption mode and key +derivation option for the PLAIN format. + +This change will cause backward incompatibility. +For this reason, the user will have to specify the exact parameters +for cipher, key size, and key derivation parameters for plain format. + +The default encryption mode will be AES-XTS with 512bit key (AES-256). +The CBC mode is no longer considered the best default, as it allows easy +bit-flipped ciphertext modification attacks and performance problems. + +For the passphrase hashing in plain mode, the encryption key is directly +derived through iterative hashing from a user-provided passphrase +(except a keyfile that is not hashed). + +The default hash is RIPEMD160, which is no longer the best default +option. The exact change will be yet discussed but should include +the possibility of using a password-based key derivation function +instead of iterative hashing. diff --git a/docs/v2.6.1-ReleaseNotes b/docs/v2.6.1-ReleaseNotes new file mode 100644 index 0000000..82012b9 --- /dev/null +++ b/docs/v2.6.1-ReleaseNotes @@ -0,0 +1,50 @@ +Cryptsetup 2.6.1 Release Notes +============================== +Stable bug-fix release with minor extensions. + +All users of cryptsetup 2.6.0 should upgrade to this version. + +Changes since version 2.6.0 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* bitlk: Fixes for BitLocker-compatible on-disk metadata parser + (found by new cryptsetup OSS-Fuzz fuzzers). + - Fix a possible memory leak if the metadata contains more than + one description field. + - Harden parsing of metadata entries for key and description entries. + - Fix broken metadata parsing that can cause a crash or out of memory. + +* Fix possible iteration overflow in OpenSSL2 PBKDF2 crypto backend. + OpenSSL2 uses a signed integer for PBKDF2 iteration count. + As cryptsetup uses an unsigned value, this can lead to overflow and + a decrease in the actual iteration count. + This situation can happen only if the user specifies + --pbkdf-force-iterations option. + OpenSSL3 (and other supported crypto backends) are not affected. + +* Fix compilation for new ISO C standards (gcc with -std=c11 and higher). + +* fvault2: Fix compilation with very old uuid.h. + +* verity: Fix possible hash offset setting overflow. + +* bitlk: Fix use of startup BEK key on big-endian platforms. + +* Fix compilation with latest musl library. + Recent musl no longer implements lseek64() in some configurations. + Use lseek() as 64-bit offset is mandatory for cryptsetup. + +* Do not initiate encryption (reencryption command) when the header and + data devices are the same. + If data device reduction is not requsted, this leads to data corruption + since LUKS metadata was written over the data device. + +* Fix possible memory leak if crypt_load() fails. + +* Always use passphrases with a minimal 8 chars length for benchmarking. + Some enterprise distributions decided to set an unconditional check + for PBKDF2 password length when running in FIPS mode. + This questionable change led to unexpected failures during LUKS format + and keyslot operations, where short passwords were used for + benchmarking PBKDF2 speed. + PBKDF2 benchmark calculations should not be affected by this change. -- cgit v1.2.3