diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Keyring.txt | 51 | ||||
| -rw-r--r-- | docs/LUKS2-locking.txt | 66 | ||||
| -rw-r--r-- | docs/doxyfile | 46 | ||||
| -rw-r--r-- | docs/examples/crypt_log_usage.c | 2 | ||||
| -rw-r--r-- | docs/examples/crypt_luks_usage.c | 2 | ||||
| -rw-r--r-- | docs/on-disk-format-luks2.pdf | bin | 382277 -> 372980 bytes | |||
| -rw-r--r-- | docs/v2.7.0-ReleaseNotes | 437 |
7 files changed, 558 insertions, 46 deletions
diff --git a/docs/Keyring.txt b/docs/Keyring.txt index bdcc838..afe071a 100644 --- a/docs/Keyring.txt +++ b/docs/Keyring.txt @@ -12,30 +12,53 @@ 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 +Currently, cryptsetup loads VK in 'logon' type kernel key so that VK is passed in +the kernel and can't be read from userspace afterwards. Also, cryptsetup loads VK in +the 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 +cryptsetup process exits (for whatever reason) the key gets unlinked in the 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. +used cryptsetup 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). +always at least one copy in the kernel crypto layer). + +Additionally, libcryptsetup supports the linking of volume keys to +user-specified kernel keyring with crypt_set_keyring_to_link(). The user may +specify keyring name, key type ('user' or 'logon') and key description where +libcryptsetup should link the verified volume key upon subsequent device +activation (or key verification alone). + +The volume key(s) (provided the key type is 'user') linked in the user keyring +can be later used to activate the device via crypt_activate_by_keyslot_context() +with CRYPT_KC_TYPE_VK_KEYRING type keyslot context +(acquired by crypt_keyslot_context_init_by_vk_in_keyring()). + +Example of how to use volume key linked in custom user keyring from cryptsetup +utility: + +1) Open the device and store the volume key to the session keyring: +# cryptsetup open <device> --link-vk-to-keyring "@s::%user:testkey" tst + +2) Add a keyslot using the stored volume key in a keyring: +# cryptsetup luksAddKey <device> --volume-key-keyring "%user:testkey" + +3) Activate the device using the volume key cached in a keyring ('user' type key) +# cryptsetup open <device> <active_name> --volume-key-keyring "testkey" 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 +passphrase stored in kernel keyring instead. The user may load the passphrase in the 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 +(luks2-keyring). The library also provides a general method for device activation by +reading the passphrase from the 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. +data from userspace unlike with VK in I). The ability to read keyslot passphrases +from kernel keyring also allows easy auto-activate LUKS2 devices. -Simple example how to use kernel keyring for keyslot passphrase: +Simple example of 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 @@ -43,7 +66,7 @@ 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 +3) Activate the device using the passphrase stored in the kernel keyring cryptsetup open /dev/device my_unlocked_device 4a) unlink the key when no longer needed by @@ -52,5 +75,5 @@ 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 +If cryptsetup asks for a 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 index e401b61..ccc80d8 100644 --- a/docs/LUKS2-locking.txt +++ b/docs/LUKS2-locking.txt @@ -5,7 +5,7 @@ Why ~~~ LUKS2 format keeps two identical copies of metadata stored consecutively -at the head of metadata device (file or bdev). The metadata +at the head of the 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. @@ -15,17 +15,17 @@ 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 +easily become read-update operation silently without the user's knowledge. +A major feature of the 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 +while creating a partition on a mistaken block device). +Such header corruption is detected early on the header read and the 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 +On current Linux systems header load operation may be triggered without the user +direct intervention for example by an udev rule or from a systemd service. +Such a clash of header read and auto-recovery procedure could have severe +consequences with the worst case of having a LUKS2 device inaccessible or being broken beyond repair. The whole locking of LUKSv2 device headers split into two categories depending @@ -36,17 +36,17 @@ 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 +from major:minor couple of the affected block device. Note we recommend +that access to the private locking directory is supposed to be limited +to the 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 +A 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 +manipulated by the regular user, unlike headers on block devices. Therefore we perform flock() protection on file with the luks2 header directly. Limitations @@ -58,4 +58,40 @@ 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. +b) The locking is not cluster-aware in any way. + +Additional LUKS2 locks +====================== + +LUKS2 reencryption device lock +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Device in LUKS2 reencryption is protected by an exclusive lock placed in the default +locking directory. The lock's purpose is to exclude multiple processes from +performing reencryption on the same device (identified by LUKS uuid). The lock +is taken no matter the LUKS2 reencryption mode (online or offline). + +LUKS2 memory hard global lock +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An optional global lock that makes libcryptsetup serialize memory hard +pbkdf function when deriving a key encryption key from passphrase on unlocking +LUKS2 keyslot. The lock has to be enabled via the CRYPT_ACTIVATE_SERIALIZE_MEMORY_HARD_PBKDF +flag. The lock is placed in the default locking directory. + +LUKS2 OPAL lock +~~~~~~~~~~~~~~~ + +Exclusive per device lock taken when manipulating LUKS2 device configured for use with +SED OPAL2 locking range. + +Lock ordering +============= + +To avoid a deadlock following rules must apply: + +- LUKS2 reencrytpion lock must be taken before LUKS2 OPAL lock. + +- LUKS2 OPAL lock must be taken before LUKS2 metadata lock. + +- LUKS2 memory hard global lock can not be used with other locks. diff --git a/docs/doxyfile b/docs/doxyfile index 0943772..86cbdb0 100644 --- a/docs/doxyfile +++ b/docs/doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.9.1 +# Doxyfile 1.9.8 #--------------------------------------------------------------------------- # Project related configuration options @@ -10,9 +10,9 @@ PROJECT_BRIEF = "Public cryptsetup API" PROJECT_LOGO = OUTPUT_DIRECTORY = doxygen_api_docs CREATE_SUBDIRS = NO +CREATE_SUBDIRS_LEVEL = 8 ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -OUTPUT_TEXT_DIRECTION = None BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = @@ -39,6 +39,7 @@ OPTIMIZE_OUTPUT_SLICE = NO EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES TOC_INCLUDE_HEADINGS = 5 +MARKDOWN_ID_STYLE = DOXYGEN AUTOLINK_SUPPORT = YES BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO @@ -52,6 +53,7 @@ INLINE_SIMPLE_STRUCTS = NO TYPEDEF_HIDES_STRUCT = YES LOOKUP_CACHE_SIZE = 0 NUM_PROC_THREADS = 1 +TIMESTAMP = NO #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -72,6 +74,7 @@ INTERNAL_DOCS = NO CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO HIDE_COMPOUND_REFERENCE= NO +SHOW_HEADERFILE = YES SHOW_INCLUDE_FILES = YES SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = NO @@ -101,9 +104,12 @@ QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES WARN_NO_PARAMDOC = NO +WARN_IF_UNDOC_ENUM_VAL = NO WARN_AS_ERROR = NO WARN_FORMAT = "$file:$line: $text" +WARN_LINE_FORMAT = "at line $line of file $file" WARN_LOGFILE = #--------------------------------------------------------------------------- # Configuration options related to the input files @@ -111,6 +117,7 @@ WARN_LOGFILE = INPUT = doxygen_index.h \ ../lib/libcryptsetup.h INPUT_ENCODING = UTF-8 +INPUT_FILE_ENCODING = FILE_PATTERNS = RECURSIVE = NO EXCLUDE = @@ -126,6 +133,7 @@ FILTER_PATTERNS = FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = USE_MDFILE_AS_MAINPAGE = +FORTRAN_COMMENT_AFTER = 72 #--------------------------------------------------------------------------- # Configuration options related to source browsing #--------------------------------------------------------------------------- @@ -158,15 +166,17 @@ HTML_FOOTER = HTML_STYLESHEET = HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = +HTML_COLORSTYLE = AUTO_LIGHT HTML_COLORSTYLE_HUE = 220 HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES HTML_DYNAMIC_MENUS = YES HTML_DYNAMIC_SECTIONS = NO +HTML_CODE_FOLDING = YES HTML_INDEX_NUM_ENTRIES = 100 GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_FEEDURL = DOCSET_BUNDLE_ID = org.doxygen.Project DOCSET_PUBLISHER_ID = org.doxygen.Publisher DOCSET_PUBLISHER_NAME = Publisher @@ -177,6 +187,7 @@ GENERATE_CHI = NO CHM_INDEX_ENCODING = BINARY_TOC = NO TOC_EXPAND = NO +SITEMAP_URL = GENERATE_QHP = NO QCH_FILE = QHP_NAMESPACE = org.doxygen.Project @@ -189,14 +200,16 @@ GENERATE_ECLIPSEHELP = NO ECLIPSE_DOC_ID = org.doxygen.Project DISABLE_INDEX = NO GENERATE_TREEVIEW = NO +FULL_SIDEBAR = NO ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +OBFUSCATE_EMAILS = YES HTML_FORMULA_FORMAT = png FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES FORMULA_MACROFILE = USE_MATHJAX = NO +MATHJAX_VERSION = MathJax_2 MATHJAX_FORMAT = HTML-CSS MATHJAX_RELPATH = http://www.mathjax.org/mathjax MATHJAX_EXTENSIONS = @@ -227,9 +240,7 @@ 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 @@ -240,7 +251,6 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -RTF_SOURCE_CODE = NO #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -261,12 +271,17 @@ XML_NS_MEMB_FILE_SCOPE = NO #--------------------------------------------------------------------------- GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- +# Configuration options related to Sqlite3 output +#--------------------------------------------------------------------------- +GENERATE_SQLITE3 = NO +SQLITE3_OUTPUT = sqlite3 +SQLITE3_RECREATE_DB = YES +#--------------------------------------------------------------------------- # Configuration options related to the Perl module output #--------------------------------------------------------------------------- GENERATE_PERLMOD = NO @@ -294,15 +309,14 @@ ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES #--------------------------------------------------------------------------- -# Configuration options related to the dot tool +# Configuration options related to diagram generator tools #--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES -DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = NO DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 +DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" +DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" +DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" DOT_FONTPATH = CLASS_GRAPH = YES COLLABORATION_GRAPH = YES @@ -318,18 +332,20 @@ CALL_GRAPH = NO CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES +DIR_GRAPH_MAX_DEPTH = 1 DOT_IMAGE_FORMAT = png INTERACTIVE_SVG = NO DOT_PATH = DOTFILE_DIRS = -MSCFILE_DIRS = +DIA_PATH = 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 +MSCGEN_TOOL = +MSCFILE_DIRS = diff --git a/docs/examples/crypt_log_usage.c b/docs/examples/crypt_log_usage.c index 3d08c34..4d4cb92 100644 --- a/docs/examples/crypt_log_usage.c +++ b/docs/examples/crypt_log_usage.c @@ -1,7 +1,7 @@ /* * libcryptsetup API log example * - * Copyright (C) 2011-2023 Red Hat, Inc. All rights reserved. + * Copyright (C) 2011-2024 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 diff --git a/docs/examples/crypt_luks_usage.c b/docs/examples/crypt_luks_usage.c index d7779bd..b690378 100644 --- a/docs/examples/crypt_luks_usage.c +++ b/docs/examples/crypt_luks_usage.c @@ -1,7 +1,7 @@ /* * libcryptsetup API - using LUKS device example * - * Copyright (C) 2011-2023 Red Hat, Inc. All rights reserved. + * Copyright (C) 2011-2024 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 diff --git a/docs/on-disk-format-luks2.pdf b/docs/on-disk-format-luks2.pdf Binary files differindex d89bcef..e5a8f05 100644 --- a/docs/on-disk-format-luks2.pdf +++ b/docs/on-disk-format-luks2.pdf diff --git a/docs/v2.7.0-ReleaseNotes b/docs/v2.7.0-ReleaseNotes new file mode 100644 index 0000000..6af199b --- /dev/null +++ b/docs/v2.7.0-ReleaseNotes @@ -0,0 +1,437 @@ +Cryptsetup 2.7.0 Release Notes +============================== +Stable release with new features and bug fixes. + +Changes since version 2.6.1 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Introduce support for hardware OPAL disk encryption. + + Some SATA and NVMe devices support hardware encryption through OPAL2 + TCG interface (SEDs - self-encrypting drives). Using hardware disk + encryption is controversial as you must trust proprietary hardware. + + On the other side, using both software and hardware encryption + layers increases the security margin by adding an additional layer + of protection. There is usually no performance drop if OPAL encryption + is used (the drive always operates with full throughput), and it does + not add any utilization to the main CPU. + + LUKS2 now supports hardware encryption through the Linux kernel + SED OPAL interface (CONFIG_BLK_SED_OPAL Linux kernel option must be + enabled). Cryptsetup OPAL is never enabled by default; you have to use + luksFormat parameters to use it. OPAL support can be disabled during + the build phase with --disable-hw-opal configure option. + + LUKS2 OPAL encryption is configured the same way as software encryption + - it stores metadata in the LUKS2 header and activates encryption for + the data area on the disk (configured OPAL locking range). + LUKS2 header metadata must always be visible (thus not encrypted). + The key stored in LUKS2 keyslots contains two parts - volume key + for software (dm-crypt) encryption and unlocking key for OPAL. + OPAL unlocking key is independent of the dm-crypt volume key and is + always 256 bits long. Cryptsetup does not support full drive OPAL + encryption; only a specific locking range is always used. + + If the OPAL device is in its initial factory state (after factory + reset), cryptsetup needs to configure the OPAL admin user and password. + If the OPAL admin user is already set, the OPAL password must be + provided during luksFormat. + The provided password is needed only to configure or reset the OPAL + locking range; LUKS device activation requires LUKS passphrase only. + LUKS passphrase should be different from OPAL password (OPAL admin user + is configured inside OPAL hardware while LUKS unlocking passphrase + unlocks LUKS keyslot). + + OPAL encryption can be used in combination with software (dm-crypt) + encryption (--hw-opal option) or without the software layer + (--hw-opal-only option). + You can see the configured segment parameters in the luksDump command. + LUKS2 devices with OPAL segments set a new requirement flag in + the LUKS2 header to prevent older cryptsetup metadata manipulation. + Do not use hardware-only encryption if you do not fully trust your + hardware vendor. + + Compatibility notes: + - Linux kernel SED interface does NOT work through USB external + adapters due to the missing compatibility layer in Linux USB storage + drivers (even if USB hardware itself can support OPAL commands). + - other TCG security subsystems like Ruby or Pyrite are not + supported. Note that many drives support only Pyrite subsystem that + does NOT encrypt data (it provides only authentication). + - compatibility among OPAL-enabled drives is often very problematic, + specifically for older drives. Many drives have bugs in the firmware + that make the Linux kernel interface unusable. + - if you forget the OPAL admin password, the only way to recover is + the full drive factory reset through the PSID key (usually printed + on the drive itself) that wipes all data on the drive (not only the + LUKS area). + - cryptsetup reencryption is not supported for LUKS2 OPAL-enabled + devices + - most OPAL drives use AES-XTS cipher mode (older drives can use + AES-CBC). This information is not available through kernel SED API. + - locked OPAL locking ranges return IO errors while reading; this + can produce a lot of scary messages in the log if some tools (like + blkid) try to read the locked area. + + Examples: + + * Formatting the drive + Use --hw-opal with luksFormat (or --hw-opal-only for hardware only + encryption): + + # cryptsetup luksFormat --hw-opal <device> + Enter passphrase for <device>: *** + Enter OPAL Admin password: *** + + * Check configuration with luksDump. + Note "hw-opal-crypt" segment that uses both dm-crypt and OPAL + encryption - keyslot stores 768 bits key (512 sw + 256 bits OPAL key). + + # cryptsetup luksDump <device> + LUKS header information + Version: 2 + ... + Data segments: + 0: hw-opal-crypt + offset: 16777216 [bytes] + length: ... [bytes] + cipher: aes-xts-plain64 + sector: 512 [bytes] + HW OPAL encryption: + OPAL segment number: 1 + OPAL key: 256 bits + OPAL segment length: ... [bytes] + Keyslots: + 0: luks2 + Key: 768 bits + ... + + For devices with OPAL encryption ONLY (only 256 bits OPAL unlocking + key is stored): + LUKS header information + Version: 2 + ... + + Data segments: + 0: hw-opal + offset: 16777216 [bytes] + length: ... [bytes] + cipher: (no SW encryption) + HW OPAL encryption: + OPAL segment number: 1 + OPAL key: 256 bits + OPAL segment length: ... [bytes] + Keyslots: + 0: luks2 + Key: 256 bits + ... + + * Activation and deactivation (open, close, luksSuspend, luksResume) + with OPAL works the same as for the LUKS2 device. + + * Erase LUKS metadata (keyslots) and remove OPAL locking range: + # cryptsetup luksErase <device> + Enter OPAL Admin password: *** + + The LUKS header is destroyed (unlike in normal LUKS luksErase) as + data are no longer accessible even with previous volume key knowledge. + + * Factory reset OPAL drive (if you do not know the Admin password). + You need the PSID (physical presence security ID), which is usually + printed on the device label. Note this will reset the device to + factory state, erasing all data on it (not only LUKS). + + # cryptsetup luksErase --hw-opal-factory-reset <device> + Enter OPAL PSID: *** + +* plain mode: Set default cipher to aes-xts-plain64 and password hashing + to sha256. + + NOTE: this is a backward incompatible change for plain mode (if you + rely on defaults). It is not relevant for LUKS devices. + + The default plain encryption mode was CBC for a long time, with many + performance problems. Using XTS mode aligns it with LUKS defaults. + + The hash algorithm for plain mode was ripemd160, which is considered + deprecated, so the new default is sha256. + + The default key size remains 256 bits (it means using AES-128 as XTS + requires two keys). + + Always specify cipher, hash, and key size for plain mode (or even + better, use LUKS as it stores all options in its metadata on disk). + As we need to upgrade algorithms from time to time because of security + reasons, cryptsetup now warns users to specify these options explicitly + in the open cryptsetup command if plain mode is used. + Cryptsetup does not block using any legacy encryption type; just it + must be specified explicitly on the cryptsetup command line. + + You can configure these defaults during build time if you need to + enforce backward compatibility. + To get the backward-compatible setting, use: + --with-plain-hash=ripemd160 --with-plain-cipher=aes + --with-plain-mode=cbc-essiv:sha256 + + Compiled-in defaults are visible in cryptsetup --help output. + +* Allow activation (open), luksResume, and luksAddKey to use the volume + key stored in a keyring. +* Allow to store volume key to a user-specified keyring in open and + luksResume commands. + + These options are intended to be used for integration with other + systems for automation. + + Users can now use the volume key (not passphrase) stored in arbitrary + kernel keyring and directly use it in particular cryptsetup commands + with --volume-key-keyring option. The keyring can use various policies + (set outside of the cryptsetup scope, for example, by keyctl). + + The --volume-key-keyring option takes a key description in + keyctl-compatible syntax and can either be a numeric key ID or + a string name in the format [%<key type>:]<key name>. + The default key type is "user". + + To store the volume key in a keyring, you can use cryptsetup with + --link-vk-to-keyring option that is available for open and luksResume + cryptsetup command. The option argument has a more complex format: + <keyring_description>::<key_description>. + The <keyring_description> contains the existing kernel keyring + description (numeric id or keyctl format). The <keyring_description> + may be optionally prefixed with "%:" or "%keyring:". The string "::" is + a delimiter that separates keyring and key descriptions. + The <key_description> has the same syntax as used in the + --volume-key-keyring option. + + Example: + + Open the device and store the volume key to the keyring: + # cryptsetup open <device> --link-vk-to-keyring "@s::%user:testkey" tst + + Add keyslot using the stored key in a keyring: + # cryptsetup luksAddKey <device> --volume-key-keyring "%user:testkey" + +* Do not flush IO operations if resize grows the device. + This can help performance in specific cases where the encrypted device + is extended automatically while running many IO operations. + +* Use only half of detected free memory for Argon2 PBKDF on systems + without swap (for LUKS2 new keyslot or format operations). + + This should avoid out-of-memory crashes on low-memory systems without + swap. The benchmark for memory-hard KDF during format is tricky, and + it seems that relying on the maximum half of physical memory is not + enough; relying on free memory should bring the needed security margin + while still using Argon2. + There is no change for systems with active swap. + Note, for very-low memory-constrained systems, a user should avoid + memory-hard PBKDF completely (manually select legacy PBKDF2 instead + of Argon2); cryptsetup does not change PBKDF automatically. + +* Add the possibility to specify a directory for external LUKS2 token + handlers (plugins). + + Use --external-tokens-path parameter in cryptsetup or + crypt_token_set_external_path API call. The parameter is required to be + an absolute path, and it is set per process context. This parameter is + intended mainly for testing and developing new tokens. + +* Do not allow reencryption/decryption on LUKS2 devices with + authenticated encryption or hardware (OPAL) encryption. + + The operation fails later anyway; cryptsetup now detects incompatible + parameters early. + +* Do not fail LUKS format if the operation was interrupted on subsequent + device wipe. + + Device wipe (used with authenticated encryption) is an optional + operation and can be interrupted; not yet wiped part of the device will + only report integrity errors (until overwritten with new data). + +* Fix the LUKS2 keyslot option to be used while activating the device + by a token. + + It can also be used to check if a specific token (--token-id) can + unlock a specific keyslot (--key-slot option) when --test-passphrase + option is specified. + +* Properly report if the dm-verity device cannot be activated due to + the inability to verify the signed root hash (ENOKEY). + +* Fix to check passphrase for selected keyslot only when adding + new keyslot. + + If the user specifies the exact keyslot to unlock, cryptsetup no longer + checks other keyslots. + +* Fix to not wipe the keyslot area before in-place overwrite. + + If the LUKS2 keyslot area has to be overwritten (due to lack of free + space for keyslot swap), cryptsetup does not wipe the affected area as + the first step (it will be overwritten later anyway). + Previously, there was an unnecessary risk of losing the keyslot data + if the code crashed before adding the new keyslot. + + If there is enough space in the keyslot area, cryptsetup never + overwrites the older keyslot before the new one is written correctly + (even if the keyslot number remains the same). + +* bitlk: Fix segfaults when attempting to verify the volume key. + + Also, clarify that verifying the volume key is impossible without + providing a passphrase or recovery key. + +* Add --disable-blkid command line option to avoid blkid device check. + +* Add support for the meson build system. + + All basic operations are supported (compile, test, and dist) with some + minor exceptions; please see the meson manual for more info. + + The Meson build system will completely replace autotools in some future + major release. Both autotools and meson build systems are supported, + and the release archive is built with autotools. + +* Fix wipe operation that overwrites the whole device if used for LUKS2 + header with no keyslot area. + + Formatting a LUKS2 device with no defined keyslots area is a very + specific operation, and the code now properly recognizes such + configuration. + +* Fix luksErase to work with detached LUKS header. + +* Disallow the use of internal kernel crypto driver names in "capi" + specification. + + The common way to specify cipher mode in cryptsetup is to use + cipher-mode-iv notation (like aes-xts-plain64). + With the introduction of authenticated ciphers, we also allow + "capi:<spec>" notation that is directly used by dm-crypt + (e.g., capi:xts(aes)-plain64). + + CAPI specification was never intended to be used directly in the LUKS + header; unfortunately, the code allowed it until now. + Devices with CAPI specification in metadata can no longer be activated; + header repair is required. + + CAPI specification could allow attackers to change the cipher + specification to enforce loading some specific kernel crypto driver + (for example, load driver with known side-channel issues). + This can be problematic, specifically in a cloud environment + (modifying LUKS2 metadata in container image). + + Thanks to Jan Wichelmann, Luca Wilke, and Thomas Eisenbarth from + University of Luebeck for noticing the problems with this code. + +* Fix reencryption to fail early for unknown cipher. + +* tcrypt: Support new Blake2 hash for VeraCrypt. + + VeraCrypt introduces support for Blake2 PRF for PBKDF2; also support it + in cryptsetup compatible tcrypt format. + +* tcrypt: use hash values as substring for limiting KDF check. + + This allows the user to specify --hash sha or --hash blake2 to limit + the KDF scan without the need to specify the full algorithm name + (similar to cipher where we already use substring match). + +* Add Aria cipher support and block size info. + + Aria cipher is similar to AES and is supported in Linux kernel crypto + API in recent releases. + It can be now used also for LUKS keyslot encryption. + +* Do not decrease PBKDF parameters if the user forces them. + + If a user explicitly specifies PBKDF parameters (like iterations, + used memory, or threads), do not limit them, even if it can cause + resource exhaustion. + The force options were mostly used for decreasing parameters, but it + should work even opposite - despite the fact it can mean an + out-of-memory crash. + + The only limits are hard limits per the PBKDF algorithm. + +* Support OpenSSL 3.2 Argon2 implementation. + + Argon2 is now available directly in OpenSSL, so the code no longer + needs to use libargon implementation. + Configure script should detect this automatically. + +* Add support for Argon2 from libgcrypt + (requires yet unreleased gcrypt 1.11). + + Argon2 has been available since version 1.10, but we need version 1.11, + which will allow empty passwords. + +* Used Argon2 PBKDF implementation is now reported in debug mode + in the cryptographic backend version. For native support in + OpenSSL 3.2 or libgcrypt 1.11, "argon2" is displayed. + If libargon2 is used, "cryptsetup libargon2" (for embedded + library) or "external libargon2" is displayed. + +* Link only libcrypto from OpenSSL. + + This reduces dependencies as other OpenSSL libraries are not needed. + +* Disable reencryption for Direct-Access (DAX) devices. + + Linux kernel device-mapper cannot stack DAX/non-DAX devices in + the mapping table, so online reencryption cannot work. Detect DAX + devices and warn users during LUKS format. Also, DAX or persistent + memory devices do not provide atomic sector updates; any single + modification can corrupt the whole encryption block. + +* Print a warning message if the device is not aligned to sector size. + + If a partition is resized after format, activation could fail when + the device is not multiple of a sector size. Print at least a warning + here, as the activation error message is visible only in kernel syslog. + +* Fix sector size and integrity fields display for non-LUKS2 crypt + devices for the status command. + +* Fix suspend for LUKS2 with authenticated encryption (also suspend + dm-integrity device underneath). + + This should stop the dm-integrity device from issuing journal updates + and possibly corrupt data if the user also tries to modify the + underlying device. + +* Update keyring and locking documentation and LUKS2 specification + for OPAL2 support. + +Libcryptsetup API extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The libcryptsetup API is backward compatible for all existing symbols. + +New symbols: + crypt_activate_by_keyslot_context + crypt_format_luks2_opal + crypt_get_hw_encryption_type + crypt_get_hw_encryption_key_size + crypt_keyslot_context_init_by_keyring + crypt_keyslot_context_init_by_vk_in_keyring + crypt_keyslot_context_init_by_signed_key + crypt_resume_by_keyslot_context + crypt_token_set_external_path + crypt_set_keyring_to_link + crypt_wipe_hw_opal + +New defines (hw encryption status): + CRYPT_SW_ONLY + CRYPT_OPAL_HW_ONLY + CRYPT_SW_AND_OPAL_HW + +New keyslot context types: + CRYPT_KC_TYPE_KEYRING + CRYPT_KC_TYPE_VK_KEYRING + CRYPT_KC_TYPE_SIGNED_KEY + +New requirement flag: + CRYPT_REQUIREMENT_OPAL |