"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/v2.0.0-ReleaseNotes" (24 Jul 2021, 26629 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.

    1 Cryptsetup 2.0.0 Release Notes
    2 ==============================
    3 Stable release with experimental features.
    4 
    5 This version introduces a new on-disk LUKS2 format.
    6 
    7 The legacy LUKS (referenced as LUKS1) will be fully supported
    8 forever as well as a traditional and fully backward compatible format.
    9 
   10 NOTE: This version changes soname of libcryptsetup library and increases
   11 major version for all public symbols.
   12 Most of the old functions are fully backward compatible, so only
   13 recompilation of programs should be needed.
   14 
   15 Please note that authenticated disk encryption, non-cryptographic
   16 data integrity protection (dm-integrity), use of Argon2 Password-Based
   17 Key Derivation Function and the LUKS2 on-disk format itself are new
   18 features and can contain some bugs.
   19 
   20 To provide all security features of authenticated encryption we need
   21 better nonce-reuse resistant algorithm in kernel (see note below).
   22 For now, please use authenticated encryption as experimental feature.
   23 
   24 Please do not use LUKS2 without properly configured backup or in
   25 production systems that need to be compatible with older systems.
   26 
   27 Changes since version 2.0.0-RC1
   28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   29 * Limit KDF requested (for format) memory by available physical memory.
   30   On some systems too high requested amount of memory causes OOM killer
   31   to kill the process (instead of returning ENOMEM).
   32   We never try to use more than half of available physical memory.
   33 
   34 * Ignore device alignment if it is not multiple of minimal-io.
   35   Some USB enclosures seems to report bogus topology info that
   36   prevents to use LUKS detached header.
   37 
   38 Changes since version 2.0.0-RC0
   39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   40 
   41 * Enable to use system libargon2 instead of bundled version.
   42   Renames --disable-argon2 to --disable-internal-argon2 option
   43   and adds --enable-libargon2 flag to allow system libargon2.
   44 
   45 * Changes in build system (Automake)
   46   - The build system now uses non-recursive automake (except for tests).
   47   (Tools binaries are now located in buildroot directory.)
   48   - New --disable-cryptsetup option to disable build of cryptsetup tool.
   49   - Enable build of cryptsetup-reencrypt by default.
   50 
   51 * Install tmpfiles.d configuration for LUKS2 locking directory.
   52   You can overwrite this using --with-tmpfilesdir configure option.
   53   If your distro does not support tmpfiles.d directory, you have
   54   to create locking directory (/run/lock/cryptsetup) in cryptsetup
   55   package (or init scripts).
   56 
   57 * Adds limited support for offline reencryption of LUKS2 format.
   58 
   59 * Decrease size of testing images (and the whole release archive).
   60 
   61 * Fixes for several memory leaks found by Valgrind and Coverity tools.
   62 
   63 * Fixes for several typos in man pages and error messages.
   64 
   65 * LUKS header file in luksFormat is now automatically created
   66   if it does not exist.
   67 
   68 * Do not allow resize if device size is not aligned to sector size.
   69 
   70 Cryptsetup 2.0.0 RC0 Release Notes
   71 ==================================
   72 
   73 Important features
   74 ~~~~~~~~~~~~~~~~~~
   75 
   76 * New command integritysetup: support for the new dm-integrity kernel target.
   77 
   78   The dm-integrity is a new kernel device-mapper target that introduces
   79   software emulation of per-sector integrity fields on the disk sector level.
   80   It is available since Linux kernel version 4.12.
   81 
   82   The provided per-sector metadata fields can be used for storing a data
   83   integrity checksum (for example CRC32).
   84   The dm-integrity implements data journal that enforces atomic update
   85   of a sector and its integrity metadata.
   86 
   87   Integritysetup is a CLI utility that can setup standalone dm-integrity
   88   devices (that internally check integrity of data).
   89 
   90   Integritysetup is intended to be used for settings that require
   91   non-cryptographic data integrity protection with no data encryption.
   92   Fo setting integrity protected encrypted devices, see disk authenticated
   93   encryption below.
   94 
   95   Note that after formatting the checksums need to be initialized;
   96   otherwise device reads will fail because of integrity errors.
   97   Integritysetup by default tries to wipe the device with zero blocks
   98   to avoid this problem. Device wipe can be time-consuming, you can skip
   99   this step by specifying --no-wipe option.
  100   (But note that not wiping device can cause some operations to fail
  101   if a write is not multiple of page size and kernel page cache tries
  102   to read sectors with not yet initialized checksums.)
  103 
  104   The default setting is tag size 4 bytes per-sector and CRC32C protection.
  105   To format device with these defaults:
  106   $ integritysetup format <device>
  107   $ integritysetup open <device> <name>
  108 
  109   Note that used algorithm (unlike tag size) is NOT stored in device
  110   kernel superblock and if you use different algorithm, you MUST specify
  111   it in every open command, for example:
  112   $ integritysetup format <device> --tag-size 32 --integrity sha256
  113   $ integritysetup open <device> <name> --integrity sha256
  114 
  115   For more info, see integrity man page.
  116 
  117 * Veritysetup command can now format and activate dm-verity devices
  118   that contain Forward Error Correction (FEC) (Reed-Solomon code is used).
  119   This feature is used on most of Android devices already (available since
  120   Linux kernel 4.5).
  121 
  122   There are new options --fec-device, --fec-offset to specify data area
  123   with correction code and --fec-roots that set Redd-Solomon generator roots.
  124   This setting can be used for format command (veritysetup will calculate
  125   and store RS codes) or open command (veritysetup configures kernel
  126   dm-verity to use RS codes).
  127 
  128   For more info see veritysetup man page.
  129 
  130 * Support for larger sector sizes for crypt devices.
  131 
  132   LUKS2 and plain crypt devices can be now configured with larger encryption
  133   sector (typically 4096 bytes, sector size must be the power of two,
  134   maximal sector size is 4096 bytes for portability).
  135   Large sector size can decrease encryption overhead and can also help
  136   with some specific crypto hardware accelerators that perform very
  137   badly with 512 bytes sectors.
  138 
  139   Note that if you configure such a larger sector of the device that does use
  140   smaller physical sector, there is a possibility of a data corruption during
  141   power fail (partial sector writes).
  142 
  143   WARNING: If you use different sector size for a plain device after data were
  144   stored,  the decryption will produce garbage.
  145 
  146   For LUKS2, the sector size is stored in metadata and cannot be changed later.
  147 
  148 LUKS2 format and features
  149 ~~~~~~~~~~~~~~~~~~~~~~~~~
  150 The LUKS2 is an on-disk storage format designed to provide simple key
  151 management, primarily intended for Full Disk Encryption based on dm-crypt.
  152 
  153 The LUKS2 is inspired by LUKS1 format and in some specific situations (most
  154 of the default configurations) can be converted in-place from LUKS1.
  155 
  156 The LUKS2 format is designed to allow future updates of various
  157 parts without the need to modify binary structures and internally
  158 uses JSON text format for metadata. Compilation now requires the json-c library
  159 that is used for JSON data processing.
  160 
  161 On-disk format provides redundancy of metadata, detection
  162 of metadata corruption and automatic repair from metadata copy.
  163 
  164 NOTE: For security reasons, there is no redundancy in keyslots binary data
  165 (encrypted keys) but the format allows adding such a feature in future.
  166 
  167 NOTE: to operate correctly, LUKS2 requires locking of metadata.
  168 Locking is performed by using flock() system call for images in file
  169 and for block device by using a specific lock file in /run/lock/cryptsetup.
  170 
  171 This directory must be created by distribution (do not rely on internal
  172 fallback). For systemd-based distribution, you can simply install
  173 scripts/cryptsetup.conf into tmpfiles.d directory.
  174 
  175 For more details see LUKS2-format.txt and LUKS2-locking.txt in the docs
  176 directory. (Please note this is just overview, there will be more formal
  177 documentation later.)
  178 
  179 LUKS2 use
  180 ~~~~~~~~~
  181 
  182 LUKS2 allows using all possible configurations as LUKS1.
  183 
  184 To format device as LUKS2, you have to add "--type luks2" during format:
  185 
  186  $ cryptsetup luksFormat --type luks2 <device>
  187 
  188 All commands issued later will recognize the new format automatically.
  189 
  190 The newly added features in LUKS2 include:
  191 
  192 * Authenticated disk (sector) encryption (EXPERIMENTAL)
  193 
  194   Legacy Full disk encryption (FDE), for example, LUKS1, is a length-preserving
  195   encryption (plaintext is the same size as a ciphertext).
  196   Such FDE can provide data confidentiality, but cannot provide sound data
  197   integrity protection.
  198 
  199   Full disk authenticated encryption is a way how to provide both
  200   confidentiality and data integrity protection. Integrity protection here means
  201   not only detection of random data corruption (silent data corruption) but also
  202   prevention of an unauthorized intentional change of disk sector content.
  203 
  204   NOTE: Integrity protection of this type cannot prevent a replay attack.
  205   An attacker can replace the device or its part of the old content, and it
  206   cannot be detected.
  207   If you need such protection, better use integrity protection on a higher layer.
  208 
  209   For data integrity protection on the sector level, we need additional
  210   per-sector metadata space. In LUKS2 this space is provided by a new
  211   device-mapper dm-integrity target (available since kernel 4.12).
  212   Here the integrity target provides only reliable per-sector metadata store,
  213   and the whole authenticated encryption is performed inside dm-crypt stacked
  214   over the dm-integrity device.
  215 
  216   For encryption, Authenticated Encryption with Additional Data (AEAD) is used.
  217   Every sector is processed as a encryption request of this format:
  218 
  219    |----- AAD -------|------ DATA -------|-- AUTH TAG --|
  220    | (authenticated) | (auth+encryption) |              |
  221    | sector_LE |  IV |  sector in/out    |  tag in/out  |
  222 
  223   AEAD encrypts the whole sector and also authenticates sector number
  224   (to detect sector relocation) and also authenticates Initialization Vector.
  225 
  226   AEAD encryption produces encrypted data and authentication tag.
  227   The authenticated tag is then stored in per-sector metadata space provided
  228   by dm-integrity.
  229 
  230   Most of the current AEAD algorithms requires IV as a nonce, value that is
  231   never reused. Because sector number, as an IV, cannot be used in this
  232   environment, we use a new random IV (IV is a random value generated by system
  233   RNG on every write). This random IV is then stored in the per-sector metadata
  234   as well.
  235 
  236   Because the authentication tag (and IV) requires additional space, the device
  237   provided for a user has less capacity. Also, the data journalling means that
  238   writes are performed twice, decreasing throughput.
  239 
  240   This integrity protection works better with SSDs. If you want to ignore
  241   dm-integrity data journal (because journalling is performed on some higher
  242   layer or you just want to trade-off performance to safe recovery), you can
  243   switch journal off with --integrity-no-journal option.
  244   (This flag can be stored persistently as well.)
  245 
  246   Note that (similar to integritysetup) the device read will fail if
  247   authentication tag is not initialized (no previous write).
  248   By default cryptsetup run wipe of a device (writing zeroes) to initialize
  249   authentication tags. This operation can be very time-consuming.
  250   You can skip device wipe using --integrity-no-wipe option.
  251 
  252   To format LUKS2 device with integrity protection, use new --integrity option.
  253 
  254   For now, there are very few AEAD algorithms that can be used, and some
  255   of them are known to be problematic. In this release we support only
  256   a few of AEAD algorithms (options are for now hard coded), later this
  257   extension will be completely algorithm-agnostic.
  258 
  259   For testing of authenticated encryption, these algorithms work for now:
  260 
  261   1) aes-xts-plain64 with hmac-sha256 or hmac-sha512 as the authentication tag.
  262      (Common FDE mode + independent authentication tag. Authentication key
  263       for HMAC is independently generated. This mode is very slow.)
  264      $ cryptsetup luksFormat --type luks2 <device> --cipher aes-xts-plain64 --integrity hmac-sha256
  265 
  266   2) aes-gcm-random (native AEAD mode)
  267      DO NOT USE in production! The GCM mode uses only 96-bit nonce,
  268      and possible collision means fatal security problem.
  269      GCM mode has very good hardware support through AES-NI, so it is useful
  270      for performance testing.
  271      $ cryptsetup luksFormat --type luks2 <device> --cipher aes-gcm-random --integrity aead
  272 
  273   3) ChaCha20 with Poly1305 authenticator (according to RFC7539)
  274      $ cryptsetup luksFormat --type luks2 <device> --cipher chacha20-random --integrity poly1305
  275 
  276   To specify AES128/AES256 just specify proper key size (without possible
  277   authentication key). Other symmetric ciphers, like Serpent or Twofish,
  278   should work as well. The mode 1) and 2) should be compatible with IEEE 1619.1
  279   standard recommendation.
  280 
  281   There will be better suitable authenticated modes available soon
  282   For now we are just preparing framework to enable it (and hopefully improve security of FDE).
  283 
  284   FDE authenticated encryption is not a replacement for filesystem layer
  285   authenticated encryption. The goal is to provide at least something because
  286   data integrity protection is often completely ignored in today systems.
  287 
  288 * New memory-hard PBKDF
  289 
  290   LUKS1 introduced Password-Based Key Derivation Function v2 as a tool to
  291   increase attacker cost for a dictionary and brute force attacks.
  292   The PBKDF2 uses iteration count to increase time of key derivation.
  293   Unfortunately, with modern GPUs, the PBKDF2 calculations can be run
  294   in parallel and PBKDF2 can no longer provide the best available protection.
  295   Increasing iteration count just cannot prevent massive parallel dictionary
  296   password attacks in long-term.
  297 
  298   To solve this problem, a new PBKDF, based on so-called memory-hard functions
  299   can be used. Key derivation with memory-hard function requires a certain
  300   amount of memory to compute its output. The memory requirement is very
  301   costly for GPUs and prevents these systems to operate effectively,
  302   increasing cost for attackers.
  303 
  304   LUKS2 introduces support for Argon2i and Argon2id as a PBKDF.
  305   Argon2 is the winner of Password Hashing Competition and is currently
  306   in final RFC draft specification.
  307 
  308   For now, libcryptsetup contains the embedded copy of reference implementation
  309   of Argon2 (that is easily portable to all architectures).
  310   Later, once this function is available in common crypto libraries, it will
  311   switch to external implementation. (This happened for LUKS1 and PBKDF2
  312   as well years ago.)
  313   With using reference implementation (that is not optimized for speed), there
  314   is some performance penalty. However, using memory-hard PBKDF should still
  315   significantly complicate GPU-optimized dictionary and brute force attacks.
  316 
  317   The Argon2 uses three costs: memory, time (number of iterations) and parallel
  318   (number of threads).
  319   Note that time and memory cost highly influences each other (accessing a lot
  320   of memory takes more time).
  321 
  322   There is a new benchmark that tries to calculate costs to take similar way as
  323   in LUKS1 (where iteration is measured to take 1-2 seconds on user system).
  324   Because now there are more cost variables, it prefers time cost (iterations)
  325   and tries to find required memory that fits. (IOW required memory cost can be
  326   lower if the benchmarks are not able to find required parameters.)
  327   The benchmark cannot run too long, so it tries to approximate next step
  328   for benchmarking.
  329 
  330   For now, default LUKS2 PBKDF algorithm is Argon2i (data independent variant)
  331   with memory cost set to 128MB, time to 800ms and parallel thread according
  332   to available CPU cores but no more than 4.
  333 
  334   All default parameters can be set during compile time and also set on
  335   the command line by using --pbkdf, --pbkdf-memory, --pbkdf-parallel and
  336   --iter-time options.
  337   (Or without benchmark directly by using --pbkdf-force-iterations, see below.)
  338 
  339   You can still use PBKDF2 even for LUKS2 by specifying --pbkdf pbkdf2 option.
  340   (Then only iteration count is applied.)
  341 
  342 * Use of kernel keyring
  343 
  344   Kernel keyring is a storage for sensitive material (like cryptographic keys)
  345   inside Linux kernel.
  346 
  347   LUKS2 uses keyring for two major functions:
  348 
  349    - To store volume key for dm-crypt where it avoids sending volume key in
  350   every device-mapper ioctl structure. Volume key is also no longer directly
  351   visible in a dm-crypt mapping table. The key is not available for the user
  352   after dm-crypt configuration (obviously except direct memory scan).
  353   Use of kernel keyring can be disabled in runtime by --disable-keyring option.
  354 
  355    - As a tool to automatically unlock LUKS device if a passphrase is put into
  356   kernel keyring and proper keyring token is configured.
  357 
  358    This allows storing a secret (passphrase) to kernel per-user keyring by
  359   some external tool (for example some TPM handler) and LUKS2, if configured,
  360   will automatically search in the keyring and unlock the system.
  361   For more info see Tokens section below.
  362 
  363 * Persistent flags
  364   The activation flags (like allow-discards) can be stored in metadata and used
  365   automatically by all later activations (even without using crypttab).
  366 
  367   To store activation flags permanently, use activation command with required
  368   flags and add --persistent option.
  369 
  370   For example, to mark device to always activate with TRIM enabled,
  371   use (for LUKS2 type):
  372 
  373    $ cryptsetup open <device> <name> --allow-discards --persistent
  374 
  375   You can check persistent flags in dump command output:
  376 
  377   $ cryptsetup luksDump <device>
  378 
  379 * Tokens and auto-activation
  380 
  381   A LUKS2 token is an object that can be described "how to get passphrase or key"
  382   to unlock particular keyslot.
  383   (Also it can be used to store any additional metadata, and with
  384   the libcryptsetup interface it can be used to define user token types.)
  385 
  386   Cryptsetup internally implements keyring token. Cryptsetup tries to use
  387   available tokens before asking for the passphrase. For keyring token,
  388   it means that if the passphrase is available under specified identifier
  389   inside kernel keyring, the device is automatically activated using this
  390   stored passphrase.
  391 
  392   Example of using LUKS2 keyring token:
  393 
  394   # Adding token to metadata with "my_token" identifier (by default it applies to all keyslots).
  395   $ cryptsetup token add --key-description "my_token" <device>
  396 
  397   # Storing passphrase to user keyring (this can be done by an external application)
  398   $ echo -n <passphrase> | keyctl padd user my_token @u
  399 
  400   # Now cryptsetup activates automatically if it finds correct passphrase
  401   $ cryptsetup open <device> <name>
  402 
  403   The main reason to use tokens this way is to separate possible hardware
  404   handlers from cryptsetup code.
  405 
  406 * Keyslot priorities
  407 
  408   LUKS2 keyslot can have a new priority attribute.
  409   The default is "normal". The "prefer" priority tell the keyslot to be tried
  410   before other keyslots. Priority "ignore" means that keyslot will never be
  411   used if not specified explicitly (it can be used for backup administrator
  412   passwords that are used only situations when a user forgets own passphrase).
  413 
  414   The priority of keyslot can be set with new config command, for example
  415   $ cryptsetup config <device> --key-slot 1 --priority prefer
  416 
  417   Setting priority to normal will reset slot to normal state.
  418 
  419 * LUKS2 label and subsystem
  420 
  421   The header now contains additional fields for label and subsystem (additional
  422   label). These fields can be used similar to filesystem label and will be
  423   visible in udev rules to possible filtering. (Note that blkid do not yet
  424   contain the LUKS scanning code).
  425 
  426   By default both labels are empty. Label and subsystem are always set together
  427   (no option  means clear the label) with the config command:
  428 
  429   $ cryptsetup config <device> --label my_device --subsystem ""
  430 
  431 * In-place conversion form LUKS1
  432 
  433   To allow easy testing and transition to the new LUKS2 format, there is a new
  434   convert command that allows in-place conversion from the LUKS1 format and,
  435   if there are no incompatible options, also conversion back from LUKS2
  436   to LUKS1 format.
  437 
  438   Note this command can be used only on some LUKS1 devices (some device header
  439   sizes are not supported).
  440   This command is dangerous, never run it without header backup!
  441   If something fails in the middle of conversion (IO error), the header
  442   is destroyed. (Note that conversion requires move of keyslot data area to
  443   a different offset.)
  444 
  445   To convert header in-place to LUKS2 format, use
  446   $ cryptsetup convert <device> --type luks2
  447 
  448   To convert it back to LUKS1 format, use
  449   $ cryptsetup convert <device> --type luks1
  450 
  451   You can verify LUKS version with luksDump command.
  452   $ cryptsetup luksDump <device>
  453 
  454   Note that some LUKS2 features will make header incompatible with LUKS1 and
  455   conversion will be rejected (for example using new Argon2 PBKDF or integrity
  456   extensions). Some minor attributes can be lost in conversion.
  457 
  458 Other changes
  459 ~~~~~~~~~~~~~
  460 
  461 * Explicit KDF iterations count setting
  462 
  463   With new PBKDF interface, there is also the possibility to setup PBKDF costs
  464   directly, avoiding benchmarks. This can be useful if device is formatted to be
  465   primarily used on a different system.
  466 
  467   The option --pbkdf-force-iterations is available for both LUKS1 and LUKS2
  468   format. Using this option can cause device to have either very low or very
  469   high PBKDF costs.
  470   In the first case it means bad protection to dictionary attacks, in the second
  471   case, it can mean extremely high unlocking time or memory requirements.
  472   Use only if you are sure what you are doing!
  473 
  474   Not that this setting also affects iteration count for the key digest.
  475   For LUKS1 iteration count for digest will be approximately 1/8 of requested
  476   value, for LUKS2 and "pbkdf2" digest minimal PBKDF2 iteration count (1000)
  477   will be used. You cannot set lower iteration count than the internal minimum
  478   (1000 for PBKDF2).
  479 
  480   To format LUKS1 device with forced iteration count (and no benchmarking), use
  481   $ cryptsetup luksFormat <device> --pbkdf-force-iterations 22222
  482 
  483   For LUKS2 it is always better to specify full settings (do not rely on default
  484   cost values).
  485   For example, we can set to use Argon2id with iteration cost 5, memory 128000
  486   and parallel set 1:
  487   $ cryptsetup luksFormat --type luks2 <device> \
  488     --pbkdf argon2id --pbkdf-force-iterations 5 --pbkdf-memory 128000 --pbkdf-parallel 1
  489 
  490 * VeraCrypt PIM
  491 
  492   Cryptsetup can now also open VeraCrypt device that uses Personal Iteration
  493   Multiplier (PIM). PIM is an integer value that user must remember additionally
  494   to passphrase and influences PBKDF2 iteration count (without it VeraCrypt uses
  495   a fixed number of iterations).
  496 
  497   To open VeraCrypt device with PIM settings, use --veracrypt-pim (to specify
  498   PIM on the command line) or --veracrypt-query-pim to query PIM interactively.
  499 
  500 * Support for plain64be IV
  501 
  502   The plain64be is big-endian variant of plain64 Initialization Vector. It is
  503   used in some images of hardware-based disk encryption systems. Supporting this
  504   variant allows using dm-crypt to map such images through cryptsetup.
  505 
  506 * Deferral removal
  507 
  508   Cryptsetup now can mark device for deferred removal by using a new option
  509   --deferred. This means that close command will not fail if the device is still
  510   in use, but will instruct the kernel to remove the device automatically after
  511   use count drops to zero (for example, once the filesystem is unmounted).
  512 
  513 * A lot of updates to man pages and many minor changes that would make this
  514   release notes too long ;-)
  515 
  516 Libcryptsetup API changes
  517 ~~~~~~~~~~~~~~~~~~~~~~~~~
  518 
  519 These API functions were removed, libcryptsetup no longer handles password
  520 retries from terminal (application should handle terminal operations itself):
  521 	crypt_set_password_callback;
  522 	crypt_set_timeout;
  523 	crypt_set_password_retry;
  524 	crypt_set_password_verify;
  525 
  526 This call is removed (no need to keep typo backward compatibility,
  527 the proper function is crypt_set_iteration_time :-)
  528 	crypt_set_iterarion_time;
  529 
  530 These calls were removed because are not safe, use per-context
  531 error callbacks instead:
  532 	crypt_last_error;
  533 	crypt_get_error;
  534 
  535 The PBKDF benchmark was replaced by a new function that uses new KDF structure
  536 	crypt_benchmark_kdf; (removed)
  537 	crypt_benchmark_pbkdf; (new API call)
  538 
  539 These new calls are now exported, for details see libcryptsetup.h:
  540 	crypt_keyslot_add_by_key;
  541 	crypt_keyslot_set_priority;
  542 	crypt_keyslot_get_priority;
  543 
  544 	crypt_token_json_get;
  545 	crypt_token_json_set;
  546 	crypt_token_status;
  547 	crypt_token_luks2_keyring_get;
  548 	crypt_token_luks2_keyring_set;
  549 	crypt_token_assign_keyslot;
  550 	crypt_token_unassign_keyslot;
  551 	crypt_token_register;
  552 
  553 	crypt_activate_by_token;
  554 	crypt_activate_by_keyring;
  555 	crypt_deactivate_by_name;
  556 
  557 	crypt_metadata_locking;
  558 	crypt_volume_key_keyring;
  559 	crypt_get_integrity_info;
  560 	crypt_get_sector_size;
  561 	crypt_persistent_flags_set;
  562 	crypt_persistent_flags_get;
  563 	crypt_set_pbkdf_type;
  564 	crypt_get_pbkdf_type;
  565 
  566 	crypt_convert;
  567 	crypt_keyfile_read;
  568 	crypt_wipe;
  569 
  570 Unfinished things & TODO for next releases
  571 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  572 * There will be better documentation and examples.
  573 
  574 * There will be some more formal definition of the threat model for integrity
  575   protection. (And a link to some papers discussing integrity protection,
  576   once it is, hopefully, accepted and published.)
  577 
  578 * Offline re-encrypt tool LUKS2 support is currently limited.
  579   There will be online LUKS2 re-encryption tool in future.
  580 
  581 * Authenticated encryption will use new algorithms from CAESAR competition
  582   (https://competitions.cr.yp.to/caesar.html) once these algorithms are available
  583   in kernel (more on this later).
  584   NOTE: Currently available authenticated modes (GCM, Chacha20-poly1305)
  585   in kernel have too small 96-bit nonces that are problematic with
  586   randomly generated IVs (the collison probability is not negligible).
  587   For the GCM, nonce collision is a fatal problem.
  588 
  589 * Authenticated encryption do not set encryption for dm-integrity journal.
  590 
  591   While it does not influence data confidentiality or integrity protection,
  592   an attacker can get some more information from data journal or cause that
  593   system will corrupt sectors after journal replay. (That corruption will be
  594   detected though.)
  595 
  596 * Some utilities (blkid, systemd-cryptsetup) have already support for LUKS
  597   but not yet in released version (support in crypttab etc).
  598 
  599 * There are some examples of user-defined tokens inside misc/luks2_keyslot_example
  600   directory (like a simple external program that uses libssh to unlock LUKS2
  601   using remote keyfile).
  602 
  603 * The python binding (pycryptsetup) contains only basic functionality for LUKS1
  604   (it is not updated for new features) and will be deprecated soon in favor
  605   of python bindings to libblockdev library (that can already handle LUKS1 devices).