debops.cryptsetup default variables

Sections

Required packages
List of encrypted filesystems
Keyfile settings
LUKS header backup
Ciphertext block device options
Swap options
Filesystem options
Cryptography defaults
Configuration for other Ansible roles

Required packages 

cryptsetup__base_packages

List of base packages to install.

cryptsetup__base_packages:
  - 'cryptsetup'

List of encrypted filesystems 

cryptsetup__devices

Global definition list of encrypted devices.

Refer to the documentation of all options for more details.

cryptsetup__devices: []

cryptsetup__group_devices

Host group definition list of encrypted devices.

cryptsetup__group_devices: []

cryptsetup__host_devices

Host definition list of encrypted devices.

cryptsetup__host_devices: []

cryptsetup__combined_devices

Combined list of encrypted devices in the order as they will be processed.

cryptsetup__combined_devices: '{{ (cryptsetup__devices | list) +
                                  (cryptsetup__group_devices | list) +
                                  (cryptsetup__host_devices | list) }}'

cryptsetup__devices_execution_strategy

The execution strategy to use for processing the cryptsetup__combined_devices list.

serial

Process one device at a time (from start to finish) before processing the next one in the list.

This is more verbose.

parallel

Process all devices in parallel meaning that every task (like creating the keyfile or initializing LUKS) is done with all devices at a time before moving on to the next task. This means that all devices will be done at the same time.

This is more compact.

You will only need to change this when you want to use the Plaintext device mapper target of one item as the Ciphertext block device of another item. Refer to Example for chaining multiple ciphers for details.

cryptsetup__devices_execution_strategy: 'parallel'

Keyfile settings 

cryptsetup__secret_path

Location where keyfiles are generated and stored on the Ansible controller.

cryptsetup__secret_path: '{{ secret + "/cryptsetup/" + ansible_fqdn }}'

cryptsetup__secret_owner

System user who owns the secret directory and all files in it on the Ansible controller. You might want to change that if you run this role as root on the Ansible controller itself but the secrets directory is managed by another user. The default is set to the special value omit to use the owner under which the role is run.

cryptsetup__secret_owner: '{{ omit }}'

cryptsetup__secret_group

System group of the secret directory and all files in it on the Ansible controller. You might want to change that if you run this role as root on the Ansible controller itself but the secrets directory is managed by another user. The default is set to the special value omit to use the primary group under which the role is run.

cryptsetup__secret_group: '{{ omit }}'

cryptsetup__secret_mode

File mode used for the secret directory and all files in it on the Ansible controller.

cryptsetup__secret_mode: 'u=rwX,g=,o='

cryptsetup__keyfile_remote_location

Directory where the keyfiles will be stored on the remote system.

cryptsetup__keyfile_remote_location: '{{ (ansible_local.fhs.var | d("/var/local"))
                                         + "/keyfiles" }}'

cryptsetup__keyfile_owner

System user who owns the keyfiles on the remote system.

cryptsetup__keyfile_owner: 'root'

cryptsetup__keyfile_group

System group of the keyfiles on the remote system.

cryptsetup__keyfile_group: 'root'

cryptsetup__keyfile_mode

File mode used for the keyfiles on the remote system.

cryptsetup__keyfile_mode: '0600'

cryptsetup__keyfile_source_dev

The source device where the keyfile will be read from using dd.

cryptsetup__keyfile_source_dev: '/dev/random'

cryptsetup__keyfile_gen_type

Type of keyfile to generate. Supported choices: binary, text. Refer to item.keyfile_gen_type for details.

cryptsetup__keyfile_gen_type: 'binary'

cryptsetup__keyfile_gen_command

The command which should be used to generate the keyfile when item.keyfile_gen_type is set to text. Refer to item.keyfile_gen_command for details.

cryptsetup__keyfile_gen_command: 'pwgen --secure 123 1'

cryptsetup__keyfile_shred_command

Command plus options to use when shredding/deleting the keyfile on the remote system. The file to delete will be passed as last argument.

Depending on which filesystem and lower levels the keyfile is stored on, the shred operation might be of limited use e. g. because of snapshots or copy-on-write. Try it anyway. Note that there is still at least one copy of the keyfile on the Ansible controller.

cryptsetup__keyfile_shred_command: 'shred --remove --zero --iterations=42'

LUKS header backup 

cryptsetup__header_backup_remote_location

Directory where the header backups from LUKS will be stored on the remote system.

The LUKS header backup will be stored in this file:

{{ cryptsetup__header_backup_remote_location + "/" + item.name + "_header_backup.raw" }}

on the Ansible controller.

cryptsetup__header_backup_remote_location: '{{ (ansible_local.fhs.backup | d("/var/backups"))
                                               + "/luks_header_backup" }}'

cryptsetup__header_backup

Should a header backup be created and stored on the remote system and the Ansible controller? Refer to item.backup_header for details.

cryptsetup__header_backup: True

cryptsetup__header_backup_shred_command

Command plus options to use when shredding/deleting the header backup on the remote system. The file to delete will be passed as last argument.

This is technically not needed as the LUKS header is still present and left intact on the ciphertext block device, but absent is designed to remove all files/traces previously created by the role.

Also note the comment about the effectiveness on cryptsetup__keyfile_shred_command.

cryptsetup__header_backup_shred_command: 'shred --remove --zero --iterations=2'

Ciphertext block device options 

cryptsetup__use_uuid

Use the UUID of the ciphertext block device in /etc/crypttab instead of the file path given by item.ciphertext_block_device. Refer to item.use_uuid for details.

cryptsetup__use_uuid: True

Swap options 

cryptsetup__swap_priority

Default swap device priority, from -1 to 32767. Higher numbers indicate higher priority. Refer to item.swap_priority for details.

cryptsetup__swap_priority: -1

Filesystem options 

cryptsetup__fstype

Default filesystem to create and configure in /etc/fstab. Refer to item.fstype for details.

cryptsetup__fstype: 'ext4'

cryptsetup__fstab_file

File path to the fstab(5) file where file systems should be configured.

cryptsetup__fstab_file: '/etc/fstab'

cryptsetup__mount_options

List of default mount options. Refer to item.mount_options for details.

cryptsetup__mount_options:
  - 'noatime'
  - 'nodiratime'

cryptsetup__state

Default state for all devices. Refer to item.state for details.

cryptsetup__state: 'mounted'

cryptsetup__mountpoint_parent_directory

Parent directory under which all encrypted filesystems will be mounted.

cryptsetup__mountpoint_parent_directory: '/media'

Cryptography defaults 

cryptsetup__crypttab_options

Default list of options to configure for each device in /etc/crypttab. Refer to item.crypttab_options for details.

cryptsetup__crypttab_options: []

cryptsetup__crypttab_file

File path to the crypttab(5) file where encrypted file systems should be configured.

cryptsetup__crypttab_file: '/etc/crypttab'

cryptsetup__hash

Specifies the passphrase hash. For the luks item.mode it specifies the hash used in the LUKS key setup scheme and volume key digest for cryptsetup luksFormat. Corresponds with the --hash parameter.

The current default of cryptsetup (as shown by cryptsetup --help) is sha1. Set to default to use the compiled-in default of cryptsetup.

Refs: https://security.stackexchange.com/a/40218

This is the default for item.hash.

cryptsetup__hash: 'sha512'

cryptsetup__cipher

Cipher specification string. Corresponds with the --cipher parameter.

The current default of cryptsetup (as shown by cryptsetup --help) is aes-xts-plain64. Set to default to use the compiled-in default of cryptsetup.

This is the default for item.cipher.

cryptsetup__cipher: 'aes-xts-plain64'

cryptsetup__key_size

Key size in bits. The argument has to be a multiple of 8. The possible key-sizes are limited by the cipher and mode used. Corresponds with the --key-size parameter.

The current default of cryptsetup (as shown by cryptsetup --help) is 256. Set to default to use the compiled-in default of cryptsetup.

Note that in XTS mode, only half of the key size specified here will be used for the block cypher (512 will result in AES-256). Using AES-128 is still considered secure and is faster in most cases. The reason to go with a different default value then the compiled-in default of cryptsetup was to have long-term secure storage even when quantum-computing with enough stable qubits become available to your adversary. Plus, with hardware acceleration available in most x86 CPUs nowadays, it really does not make much of a difference anymore (at least for AES).

Refs: https://crypto.stackexchange.com/a/7869

This is the default for item.key_size.

cryptsetup__key_size: 512

cryptsetup__use_dev_random

Should /dev/random be used to generate the LUKS master key? Corresponds with the --use-random and --use-urandom parameters.

The current default of cryptsetup (as shown by cryptsetup --help) is /dev/urandom. Set to default to use the compiled-in default of cryptsetup.

Check random(4) and https://bettercrypto.org/ for details.

cryptsetup__use_dev_random: True

cryptsetup__iter_time

The number of milliseconds to spend with PBKDF2 passphrase processing. Corresponds with the --iter-time parameter.

The current default of cryptsetup (as shown by cryptsetup --help) is 1000 milliseconds. Set to default to use the compiled-in default of cryptsetup.

This is the default for item.iter_time.

cryptsetup__iter_time: 'default'

Configuration for other Ansible roles 

cryptsetup__persistent_paths__dependent_paths

Configuration for the debops.persistent_paths.

cryptsetup__persistent_paths__dependent_paths:

  '50_debops_cryptsetup':
    by_role: 'debops.cryptsetup'
    paths:
      - '{{ cryptsetup__fstab_file }}'
      - '{{ cryptsetup__crypttab_file }}'
      - '{{ cryptsetup__keyfile_remote_location }}'
      - '{{ cryptsetup__header_backup_remote_location }}'
      - '{{ cryptsetup__mountpoint_parent_directory }}'