"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/v2.4.0-ReleaseNotes" (13 Jan 2022, 11885 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "v2.4.0-ReleaseNotes": 2.4.0_vs_2.4.1.

    1 Cryptsetup 2.4.0 Release Notes
    2 ==============================
    3 Stable release with new features and bug fixes.
    4 
    5 This version introduces support for external libraries
    6 (plugins) for handling LUKS2 token objects.
    7 
    8 Changes since version 2.3.6
    9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
   10 
   11 * External LUKS token plugins
   12 
   13   A LUKS2 token is an object that can describe how to get a passphrase
   14   to unlock a particular keyslot. The generic metadata format is part
   15   of the LUKS2 specification.
   16 
   17   Cryptsetup 2.4 adds the possibility to implement token handlers
   18   in external libraries (possibly provided by other projects).
   19 
   20   A token library allows cryptsetup to understand metadata and provide
   21   basic operations. Currently external tokens may be used to unlock
   22   keyslots for following CLI actions: open (luksOpen),
   23   refresh (open --refresh), resize and dump (prints token specific
   24   content).
   25 
   26   LUKS2 devices cannot be resumed (luksResume action) via tokens yet.
   27   Support for resume and other actions will be added later.
   28 
   29   The library now provides an interface that automatically tries to load
   30   an external library for a token object in LUKS2 metadata.
   31 
   32   Token libraries should be installed in the cryptsetup subdirectory
   33   (usually /lib*/cryptsetup). This path is configurable through
   34   --with-luks2-external-tokens-path configure option.
   35 
   36   The external plugin loading can be compiled entirely out if
   37   --disable-external-tokens configure option is used. The external token
   38   interface can also be disabled runtime on the command line by
   39   --disable-external-tokens cryptsetup switch or by calling
   40   crypt_token_external_disable() API function.
   41 
   42   The name of the loaded token library is determined from the JSON LUKS
   43   metadata token object type. For example, "ssh" token will load library
   44   "libcryptsetup-token-ssh.so".
   45 
   46   External projects can use this interface to handle specific hardware
   47   without introducing additional dependencies to libcryptsetup core.
   48 
   49   As of cryptsetup 2.4.0 release systemd project already merged upstream
   50   native cryptsetup token handler for its systemd-tpm2 LUKS2 token
   51   released originally in systemd-v248. The token can be created using
   52   systemd-cryptenroll utility and devices may be manipulated either by
   53   systemd-cryptsetup cli or by cryptsetup for actions listed above.
   54 
   55   Other tokens like systemd-fido2 and systemd-pkcs11 are currently
   56   in-review.
   57 
   58 * Experimental SSH token
   59 
   60   As a demonstration of the external LUKS2 token interface, a new SSH
   61   token handler and cryptsetup-ssh utility is now provided and compiled
   62   by default.
   63 
   64   Crypsetup SSH token allows using remote keyfile through SSH protocol
   65   (it will authenticate through SSH certificates).
   66 
   67   You can disable the build of this token library with
   68   --disable-ssh-token configure option.
   69 
   70 To configure the token metadata, you need cryptsetup-ssh utility.
   71 
   72 Activation of the device is then performed by the cryptsetup utility.
   73 
   74 Example (how to activate LUKS2 through remote keyfile):
   75 
   76   - configure existing LUKS2 device with keyslot activated by a keyfile
   77    # cryptsetup luksAddKey <device> keyfile --key-slot 2
   78 
   79    - store that keyfile on a remote system accessible through SSH
   80 
   81    - configure SSH to use certificate for authentication
   82 
   83    - add a LUKS2 token with cryptsetup-ssh utility:
   84    # cryptsetup-ssh add <device>1 --key-slot 2 \
   85       --ssh-server test-vm \
   86       --ssh-user test \
   87       --ssh-path /home/test/keyfile \
   88       --ssh-keypath  /home/test/.ssh/test_rsa_key
   89 
   90   - you should see token metadata now with "cryptsetup luksDump ..."
   91    ...
   92    Tokens:
   93    0: ssh
   94         ssh_server: test-vm
   95         ssh_user: test
   96         ssh_path: /home/test/keyfile
   97         ssh_key_path: /home/test/.ssh/test_rsa_key
   98         Keyslot:    2
   99 
  100 
  101   - activation now should be automatic
  102   # cryptsetup open <device> test --verbose
  103     SSH token initiating ssh session.
  104     Key slot 2 unlocked.
  105     Command successful.
  106 
  107   - to remove a token, you can use "cryptsetup token remove" command
  108   (no plugin library required)
  109 
  110   Please note SSH token is just demonstration of plugin interface API,
  111   it is an EXPERIMENTAL feature.
  112 
  113 * Add cryptsetup --token-type parameter.
  114 
  115   It restricts token type to the parameter value in case no specific
  116   token-id is selected.
  117 
  118 * Support for token based activation with PIN.
  119 
  120   If specific token requires PIN to unlock keyslot passphrase and
  121   --token-only parameter was used cryptsetup asks for additional
  122   token PIN.
  123 
  124 * Respect keyslot priority with token-based activation.
  125 
  126 * Default LUKS2 PBKDF is now Argon2id
  127 
  128   Cryptsetup LUKS2 was using Argon2 while there were two versions,
  129   data-independent (Argon2i) suitable for the KDF use case and
  130   Argon2d (data-dependent). Later Argon2id was introduced as a new
  131   mandatory algorithm.
  132 
  133   We switched the password-based key derivation algorithms
  134   following the latest version of Argon2 RFC draft
  135   (https://datatracker.ietf.org/doc/draft-irtf-cfrg-argon2/) to Argon2id
  136   (from Argon2i) as it is the mandatory and primary version
  137   of the Argon2 algorithm.
  138 
  139   There is no need to modify older containers; the main reason is that
  140   RFC makes Argon2id the primary variant, while Argon2i subvariant is
  141   only optional.
  142   Argon2id provides better protection to side-channel attacks while
  143   still providing protection to time-memory tradeoffs.
  144 
  145   We will switch to OpenSSL implementation once it is available.
  146   With a crystal ball as a reference, it could happen early in
  147   OpenSSL 3.1 release.
  148   Watch https://github.com/openssl/openssl/issues/4091.
  149 
  150 * Increase minimal memory cost for Argon2 benchmark to 64MiB.
  151 
  152   This patch increases the benchmarking value to 64 MiB (as minimal
  153   suggested values in Argon2 RFC). For compatibility reasons, we still
  154   allow older limits if set by a parameter.
  155 
  156   NOTE: Argon2 RFC draft defines suggested parameters for disk
  157   encryption, but the LUKS2 approach is slightly different. We need to
  158   provide platform-independent values. The values in the draft expect
  159   64bit systems (suggesting using 6 GiB of RAM). In comparison, we need
  160   to provide compatibility with all 32bit systems, so allocating more
  161   than 4GiB memory is not an option for LUKS2.
  162 
  163   The maximal limit in LUKS2 stays for 4 GiB, and by default LUKS2 PBKDF
  164   benchmarking sets maximum to 1 GIB, preferring an increase of CPU cost
  165   while running benchmark
  166 
  167 * Autodetect optimal encryption sector size on LUKS2 format.
  168 
  169   While the support for larger encryption sectors is supported
  170   for several releases, it required an additional parameter.
  171 
  172   Code now uses automatic detection of 4096-bytes native sector devices
  173   and automatically enables 4096-bytes encryption size for LUKS2.
  174 
  175   If no setor size option is used, sector size is detected
  176   automatically by cryptsetup. For libcryptsetup API, autodetection
  177   happens once you specify sector_size to 0.
  178 
  179   NOTE: crypt_format() function runs autodetection ONLY if you
  180   recompile your application to the new API symbol version.
  181   For backward compatibility, older applications ignore this parameter.
  182 
  183 * Use VeraCrypt option by default and add --disable-veracrypt option.
  184 
  185   While TrueCrypt is no longer developed and supported since 2014,
  186   VeraCrypt devices (a successor of TrueCrypt) are much more used today.
  187 
  188   Default is now to support VeraCrypt format (in addition to TrueCrypt),
  189   making the --veracrypt option obsolete (ignored as it is the default).
  190 
  191   If you need to disable VeraCrypt support, use the new option
  192   --disable-veracrypt.
  193 
  194   This option increases the time to recognize wrong passwords because
  195   some VeraCrypt modes use a high PBKDF2 iteration count, and the code
  196   must try all variants. This could be limited by using --hash and
  197   --cipher options mentioned below.
  198 
  199 * Support --hash and --cipher to limit opening time for TCRYPT type
  200 
  201   If a user knows which particular PBKDF2 hash or cipher is used for
  202   TrueCrypt/VeraCrypt container,  TCRYPT format now supports --hash and
  203   --cipher option.
  204 
  205   Note the value means substring (all cipher chains containing
  206   the cipher substring are tried).
  207 
  208   For example, you can use
  209       # cryptsetup tcryptDump --hash sha512 <container>
  210 
  211   Note: to speed up the scan, the hash option (used for PBKDF)2 matters.
  212   Cipher variants are scanned very quickly.
  213 
  214   Use with care.
  215   It can reveal some sensitive attributes of the container!
  216 
  217 * Fixed default OpenSSL crypt backend support for OpenSSL3.
  218 
  219   For OpenSSL version 3, we need to load legacy provider for older hash
  220   and ciphers. For example, RIPEMD160 and Whirlpool hash algorithms are
  221   no longer available by default.
  222 
  223   NOTE: the plain format still uses RIPEMD160 for password hashing by
  224   default. Changing the default would cause incompatibilities for many
  225   old systems. Nevertheless, such a change will be needed very soon.
  226 
  227 * integritysetup: add integrity-recalculate-reset flag.
  228 
  229   The new dm-integrity option in kernel 5.13 can restart recalculation
  230   from the beginning of the device.
  231   It can be used to change the integrity checksum function.
  232 
  233   New integritysetup --integrity-recalculate-reset option is added to
  234   integritysetup, and CRYPT_ACTIVATE_RECALCULATE_RESET flag to API.
  235 
  236 * cryptsetup: retains keyslot number in luksChangeKey for LUKS2.
  237 
  238     In LUKS1, any change in keyslot means keyslot number change.
  239 
  240     In LUKS2, we can retain the keyslot number.
  241     Now luksKeyChange and crypt_keyslot_change_by_passphrase() API
  242     retains keyslot number for LUKS2 by default.
  243 
  244 * Fix cryptsetup resize using LUKS2 tokens.
  245 
  246   Fix a bug where cryptsetup needlessly asked for a passphrase even
  247   though the volume key was already unlocked via LUKS2 token.
  248 
  249 * Add close --deferred and --cancel-deferred options.
  250 
  251   All command-line utilities now understand deferred options for the
  252   close command. Deferred close means that the device is removed
  253   automagically after the last user closed the device.
  254   Cancel deferred means to cancel this operation (so the device remains
  255   active even if there a no longer active users).
  256 
  257   CRYPT_DEACTIVATE_DEFERRED and CRYPT_DEACTIVATE_DEFERRED_CANCEL flags
  258   are now available for API.
  259 
  260 * Rewritten command-line option parsing to avoid libpopt arguments
  261   memory leaks.
  262 
  263   Note: some distributions use patched lipopt that still leaks memory
  264   inside internal code (see Debian bug 941814).
  265 
  266 * Add --test-args option.
  267 
  268   New --test-args option can be used for syntax checking for valid
  269   command-line arguments with no actions performed.
  270   Note that it cannot detect unknown algorithm names and similar where
  271   we need call API functions.
  272 
  273 * veritysetup: add --root-hash-file option
  274   Allow passing the root hash via a file, rather than verbatim on
  275   the command line, for the open, verify, and format actions.
  276 
  277 * libcryptsetup C API extensions (see libcryptsetup.h for details)
  278 
  279   - crypt_logf - a printf like log function
  280   - crypt_dump_json - dump LUKS2 metadata in JSON format
  281   - crypt_header_is_detached - check if context use detached header
  282   - crypt_token_max - get maximal tokens number
  283   - crypt_token_external_path - get path for plugins (or NULL)
  284   - crypt_token_external_disable - disable runtime support for plugins
  285   - crypt_activate_by_token_pin - activate by token with additional PIN
  286   - crypt_reencrypt_run - fixed API for deprecated crypt_reencrypt
  287 
  288   The token plugin library interface cosists from these versioned
  289   exported symbols (for details see header file and SSH token example):
  290      cryptsetup_token_open
  291      cryptsetup_token_open_pin
  292      cryptsetup_token_buffer_free
  293      cryptsetup_token_validate
  294      cryptsetup_token_dump
  295      cryptsetup_token_version
  296 
  297  Since version 2.4 libcryptsetup uses exact symbol versioning
  298  Newly introduced functions have CRYPTSETUP_2.4 namespace (the old
  299  symbol always used CRYPTSETUP_2.0).
  300  There is no change in soname (the library is backward compatible).
  301 
  302  * Many fixes and additions to documentation and man pages.