cryptsetup-luksformat

Initialize a LUKS volume with a passphrase

$ cryptsetup luksFormat [/dev/sdXY]

$ cryptsetup luksFormat [/dev/sdXY] [path/to/keyfile]

$ cryptsetup luksFormat --label [label] [/dev/sdXY]

cryptsetup [OPTIONS] luksFormat <device>

<device>
    The block device or partition to be formatted with LUKS (e.g., /dev/sdb1).

-y, --verify-passphrase
    Prompts for passphrase verification by asking for it twice.

--type <type>
    Specifies the LUKS header type. Commonly luks1 or luks2. Default is luks2 for modern cryptsetup versions.

-s, --key-size <bits>
    Sets the master key size in bits (e.g., 256, 512). The default depends on the chosen cipher.

-h, --hash <algo>
    Specifies the hash algorithm for passphrase hashing (e.g., sha256, sha512).

-i, --iter-time <ms>
    Sets the desired PBKDF iteration time in milliseconds. A higher value increases passphrase resistance to brute-force attacks by increasing the time to unlock.

-c, --cipher <algo>
    Specifies the cipher algorithm (e.g., aes, serpent, twofish). Often combined with --cipher-mode.

--cipher-mode <mode>
    Specifies the cipher mode (e.g., cbc-essiv, xts-plain64). Usually paired with --cipher. xts-plain64 is common for disk encryption.

--pbkdf <algo>
    Specifies the PBKDF algorithm (e.g., argon2i, pbkdf2). argon2i is the default for LUKS2, offering better security than PBKDF2.

--header <file>
    Stores the LUKS header in a separate file instead of on the device itself. This can be useful for specific setups or plausible deniability.

--align-payload <sectors>
    Aligns the start of the encrypted payload to a specific sector boundary, which can improve performance on some storage devices, especially SSDs.

The command cryptsetup luksFormat (often colloquially referred to as cryptsetup-luksformat) is used to initialize a block device or a partition with the LUKS (Linux Unified Key Setup) encryption standard. LUKS provides a standard on-disk format for encrypted volumes, enabling compatibility between different tools and distributions.

When executed, cryptsetup luksFormat prompts the user to enter a passphrase, which is then used to derive master keys for encryption. It securely generates random master keys and stores them, along with the passphrase hash and PBKDF (Password-Based Key Derivation Function) parameters, in a LUKS header at the beginning of the device. This header also contains metadata about the encryption, such as the cipher algorithm and key size.

LUKS supports up to eight different 'key slots', allowing multiple passphrases or key files to unlock the same encrypted device. This feature is highly beneficial for scenarios requiring multiple users or enabling key revocation.

It's crucial to understand that running cryptsetup luksFormat is a destructive operation: it overwrites the existing data on the specified device. Therefore, it should only be used on new devices or devices where all existing data has been backed up or is no longer needed. After formatting, the device must be 'opened' (using cryptsetup open) and then typically formatted with a filesystem (e.g., ext4, XFS) before it can be used for data storage.

Data Destruction: Running cryptsetup luksFormat is a highly destructive operation that will irreversibly erase all existing data on the specified device. Always double-check the target device and ensure all critical data is backed up before proceeding.

Passphrase Security: The overall security of your encrypted volume is directly dependent on the strength and secrecy of your passphrase. Choose a long, complex, and unique passphrase that is not easily guessable.

LUKS Header Backup: The LUKS header contains crucial metadata. If it becomes corrupted or lost, your data may become inaccessible. It is strongly recommended to back up the LUKS header after formatting using the cryptsetup luksHeaderBackup command.

PBKDF Parameters: While default PBKDF parameters are often sensible, custom tuning (e.g., --iter-time for PBKDF2, or --pbkdf-memory and --pbkdf-parallel for Argon2) can significantly enhance resistance against brute-force attacks, though it will increase the time it takes to unlock the volume.

Although commonly referred to as 'cryptsetup-luksformat' or 'cryptsetup luksformat command' in informal discussions, the precise command syntax is 'cryptsetup luksFormat' (note the capital 'F' for the 'luksFormat' subcommand). The hyphenated or all-lowercase forms are common shorthand references to this specific function within the cryptsetup command-line tool suite.

After successfully formatting a device with cryptsetup luksFormat, the device is initialized for encryption but not yet ready for data storage. The subsequent steps typically involve:
1. 'Opening' the LUKS volume using cryptsetup open to create a decrypted mapping device (e.g., /dev/mapper/my_encrypted_volume).
2. Formatting this newly mapped device with a desired filesystem (e.g., mkfs.ext4 /dev/mapper/my_encrypted_volume).
3. Mounting the filesystem to a mount point (e.g., mount /dev/mapper/my_encrypted_volume /mnt/mydata) to make it accessible for reading and writing data.

The LUKS (Linux Unified Key Setup) standard was initially developed by Clemens Fruhwirth, with its first version (LUKS1) being released in 2004. It quickly became the de facto standard for full disk encryption on Linux, primarily managed by the cryptsetup utility.

A significant advancement came with the introduction of LUKS2, which debuted with cryptsetup version 2.0 in 2018. LUKS2 introduced numerous improvements, including: a more robust and extensible JSON-based header format, enhanced metadata redundancy, support for modern and stronger PBKDFs like Argon2i/Argon2id, and better integration with volume management. When using recent versions of cryptsetup, cryptsetup luksFormat defaults to creating LUKS2 volumes, providing superior security and flexibility for new encrypted devices.

cryptsetup(8), cryptsetup-open(8), cryptsetup-close(8), cryptsetup-luksAddKey(8), cryptsetup-luksRemoveKey(8), cryptsetup-luksDump(8), cryptsetup-luksHeaderBackup(8), lsblk(8), fdisk(8), parted(8), mkfs(8), mount(8)