README.md

   1 ![LUKS logo](https://gitlab.com/cryptsetup/cryptsetup/wikis/luks-logo.png)
   2
   3 What the ...?
   4 =============
   5 **Cryptsetup** is an open-source utility used to conveniently set up disk encryption based
   6 on the [dm-crypt](https://gitlab.com/cryptsetup/cryptsetup/wikis/DMCrypt) kernel module.
   7
   8 These formats are supported:
   9   * **plain** volumes,
  10   * **LUKS** volumes,
  11   * **loop-AES**,
  12   * **TrueCrypt** (including **VeraCrypt** extension),
  13   * **BitLocker**, and
  14   * **FileVault2**.
  15
  16 The project also includes a **veritysetup** utility used to conveniently setup
  17 [dm-verity](https://gitlab.com/cryptsetup/cryptsetup/wikis/DMVerity)
  18 block integrity checking kernel module and **integritysetup** to setup
  19 [dm-integrity](https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity)
  20 block integrity kernel module.
  21
  22 LUKS Design
  23 -----------
  24 **LUKS** is the standard for Linux disk encryption. By providing a standard on-disk format,
  25 it does not only facilitate compatibility among distributions, but also provides secure management
  26 of multiple user passwords. LUKS stores all necessary setup information in the partition header,
  27 enabling to transport or migrate data seamlessly.
  28
  29 ### Specification and documentation
  30
  31   * The latest version of the
  32   [LUKS2 format specification](https://gitlab.com/cryptsetup/LUKS2-docs).
  33   * The latest version of the
  34   [LUKS1 format specification](https://www.kernel.org/pub/linux/utils/cryptsetup/LUKS_docs/on-disk-format.pdf).
  35   * [Project home page](https://gitlab.com/cryptsetup/cryptsetup/).
  36   * [Frequently asked questions (FAQ)](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions)
  37
  38 Download
  39 --------
  40 All release tarballs and release notes are hosted on
  41 [kernel.org](https://www.kernel.org/pub/linux/utils/cryptsetup/).
  42
  43 **The latest stable cryptsetup release version is 2.6.1**
  44   * [cryptsetup-2.6.1.tar.xz](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.6/cryptsetup-2.6.1.tar.xz)
  45   * Signature [cryptsetup-2.6.1.tar.sign](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.6/cryptsetup-2.6.1.tar.sign)
  46     _(You need to decompress file first to check signature.)_
  47   * [Cryptsetup 2.6.1 Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.6/v2.6.1-ReleaseNotes).
  48
  49 Previous versions
  50  * [Version 2.5.0](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/cryptsetup-2.5.0.tar.xz) -
  51    [Signature](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/cryptsetup-2.5.0.tar.sign) -
  52    [Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v2.5/v2.5.0-ReleaseNotes).
  53  * [Version 1.7.5](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/cryptsetup-1.7.5.tar.xz) -
  54    [Signature](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/cryptsetup-1.7.5.tar.sign) -
  55    [Release Notes](https://www.kernel.org/pub/linux/utils/cryptsetup/v1.7/v1.7.5-ReleaseNotes).
  56
  57 Source and API documentation
  58 ----------------------------
  59 For development version code, please refer to
  60 [source](https://gitlab.com/cryptsetup/cryptsetup/tree/master) page,
  61 mirror on [kernel.org](https://git.kernel.org/cgit/utils/cryptsetup/cryptsetup.git/) or
  62 [GitHub](https://github.com/mbroz/cryptsetup).
  63
  64 For libcryptsetup documentation see
  65 [libcryptsetup API](https://mbroz.fedorapeople.org/libcryptsetup_API/) page.
  66
  67 The libcryptsetup API/ABI changes are tracked in
  68 [compatibility report](https://abi-laboratory.pro/tracker/timeline/cryptsetup/).
  69
  70 NLS PO files are maintained by
  71 [TranslationProject](https://translationproject.org/domain/cryptsetup.html).
  72
  73 Required packages
  74 -----------------
  75 All distributions provide cryptsetup as distro package. If you need to compile cryptsetup yourself,
  76 some packages are required for compilation.
  77 Please always prefer distro specific build tools to manually configuring cryptsetup.
  78
  79 Here is the list of packages needed for the compilation of project for particular distributions:
  80
  81 **For Fedora**:
  82 ```
  83 git gcc make autoconf automake gettext-devel pkgconfig openssl-devel popt-devel device-mapper-devel
  84 libuuid-devel json-c-devel libblkid-devel findutils libtool libssh-devel tar
  85
  86 Optionally: libargon2-devel libpwquality-devel
  87 ```
  88 To run the internal testsuite (make check) you also need to install
  89 ```
  90 sharutils device-mapper jq vim-common expect keyutils netcat shadow-utils openssh-clients openssh sshpass
  91 ```
  92
  93 **For Debian and Ubuntu**:
  94 ```
  95 git gcc make autoconf automake autopoint pkg-config libtool gettext libssl-dev libdevmapper-dev
  96 libpopt-dev uuid-dev libsepol1-dev libjson-c-dev libssh-dev libblkid-dev tar
  97
  98 Optionally: libargon2-0-dev libpwquality-dev
  99 ```
 100 To run the internal testsuite (make check) you also need to install
 101 ```
 102 sharutils dmsetup jq xxd expect keyutils netcat passwd openssh-client sshpass
 103 ```
 104
 105 Note that the list could change as the distributions evolve.
 106
 107 Compilation
 108 -----------
 109 The cryptsetup project uses **automake** and **autoconf** system to generate all needed files
 110 for compilation. If you check it from the git snapshot, use **./autogen.sh && ./configure && make**
 111 to compile the project. If you use downloaded released **tar.xz** archive, the configure script
 112 is already pre-generated (no need to run **autoconf.sh**).
 113 See **./configure --help** and use **--disable-[feature]** and **--enable-[feature]** options.
 114
 115 For running the test suite that come with the project, type **make check**.
 116 Note that most tests will need root user privileges and run many dangerous storage fail simulations.
 117 Do **not** run tests with root privilege on production systems! Some tests will need scsi_debug
 118 kernel module to be available.
 119
 120 For more details, please refer to [automake](https://www.gnu.org/software/automake/manual/automake.html)
 121 and [autoconf](https://www.gnu.org/savannah-checkouts/gnu/autoconf/manual/autoconf.html) manuals.
 122
 123 Help!
 124 -----
 125 ### Documentation
 126 Please read the following documentation before posting questions in the mailing list...
 127 You will be able to ask better questions and better understand the answers.
 128
 129 * [Frequently asked questions (FAQ)](https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions),
 130 * [LUKS Specifications](#specification-and-documentation), and
 131 * manuals (aka man page, man pages, man-page)
 132
 133 The FAQ is online and in the source code for the project. The Specifications are referenced above
 134 in this document. The man pages are in source and should be available after installation using
 135 standard man commands, e.g. **man cryptsetup**.
 136
 137 ### Mailing List
 138
 139 For cryptsetup and LUKS related questions, please use the cryptsetup mailing list
 140 [cryptsetup@lists.linux.dev](mailto:cryptsetup@lists.linux.dev),
 141 hosted at [kernel.org subspace](https://subspace.kernel.org/lists.linux.dev.html).
 142 To subscribe send an empty mail to
 143 [cryptsetup+subscribe@lists.linux.dev](mailto:cryptsetup+subscribe@lists.linux.dev).
 144
 145 You can also browse and/or search the mailing [list archive](https://lore.kernel.org/cryptsetup/).
 146 News (NNTP), Atom feed and git access to public inbox is available through [lore.kernel.org](https://lore.kernel.org) service.
 147
 148 The former dm-crypt [list archive](https://lore.kernel.org/dm-crypt/) is also available.