Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Next revisionBoth sides next revision
docs:guide-user:storage:disk.encryption [2018/08/26 00:58] – Fixed unable to format due to missing kernel module dbpdocs:guide-user:storage:disk.encryption [2023/01/10 20:01] – Updated required packages, added steps to make a key-file and updated decrypt.sh for use in latest openwrt with ash mitchmurder
Line 1: Line 1:
 ====== Disk Encryption ====== ====== Disk Encryption ======
- 
 You may want to encrypt your external disk to improve privacy (in case other people have physical access to your router) or so that you can securely reuse the disk later for another purpose if it's flash (see [[http://nakedsecurity.sophos.com/2011/02/20/ssds-prove-difficult-to-securely-erase/|SSDs prove difficult to securely erase]]). You may want to encrypt your external disk to improve privacy (in case other people have physical access to your router) or so that you can securely reuse the disk later for another purpose if it's flash (see [[http://nakedsecurity.sophos.com/2011/02/20/ssds-prove-difficult-to-securely-erase/|SSDs prove difficult to securely erase]]).
  
Line 6: Line 5:
  
 <code bash> <code bash>
-opkg install kmod-crypto-ecb kmod-crypto-xts kmod-crypto-iv kmod-crypto-misc kmod-crypto-user cryptsetup+opkg install kmod-crypto-ecb kmod-crypto-xts kmod-crypto-seqiv kmod-crypto-misc kmod-crypto-user cryptsetup
 </code> </code>
  
Line 12: Line 11:
  
 <code bash> <code bash>
-opkg install kmod-fs-ext4 e2fsprogs+opkg install kmod-fs-ext4 e2fsprogs
 </code> </code>
  
-There are different ways of handling the encryption key.  In this example we generate a new random key on every mount.+There are different ways of handling the encryption key. 
 +In this example we generate a new random key on every mount.
  
 | {{:meta:icons:tango:48px-dialog-warning.svg.png?nolink}} | Don't follow these instructions blindly!  Read the [[https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions|CryptSetup FAQ]] to learn more about the ''cryptsetup'' command. | | {{:meta:icons:tango:48px-dialog-warning.svg.png?nolink}} | Don't follow these instructions blindly!  Read the [[https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions|CryptSetup FAQ]] to learn more about the ''cryptsetup'' command. |
  
-The following command will create a standard encrypted container on the device or partition ''[encrypted-device]'' (eg. /dev/sda), and requires you to enter a passphrase that will be used to access the encrypted data later.  WARNING: This will destroy anything on ''[encrypted-device]''!+The following command will create a standard encrypted container on the device or partition ''[encrypted-device]'' (eg. ''/dev/sda''), and requires you to enter a passphrase that will be used to access the encrypted data later. 
 +WARNING: This will destroy anything on ''[encrypted-device]''!
  
 <code bash> <code bash>
-cryptsetup luksFormat [encrypted-device]+cryptsetup luksFormat [encrypted-device]
 </code> </code>
  
-This step may take a long time while ''/dev/random'' gathers enough entropy to generate the key.  The security of the passphrase is based on it's strength and the number of iterations it is hashed... as the CPU on embedded systems is usually slow, it's advisable to force the use of a higher iteration count for simple passphrases: use the option ''--iter-time=[milliseconds]'' to increase the iteration count (default is usually 2000 milliseconds. Note: higher values will increase the time it takes to map the device, not access it once it's mounted).+This step may take a long time while ''/dev/random'' gathers enough entropy to generate the key. 
 +The security of the passphrase is based on it's strength and the number of iterations it is hashed... as the CPU on embedded systems is usually slow, it's advisable to force the use of a higher iteration count for simple passphrases: use the option ''%%--iter-time=[milliseconds]%%'' to increase the iteration count (default is usually 2000 milliseconds. 
 +Note: higher values will increase the time it takes to map the device, not access it once it's mounted).
  
-To use the encrypted container, you must map a decrypted device... this must be done before the device can be formatted or mounted (eg. after each reboot).  The following command creates a mapping called ''[map-name]'' (you can choose the name yourself, eg. crypt) -- you must supply the same passphrase you used when performing ''luksFormat'' above.+To use the encrypted container, you must map a decrypted device... this must be done before the device can be formatted or mounted (eg. after each reboot). 
 +The following command creates a mapping called ''[map-name]'' (you can choose the name yourself, eg. crypt) -- you must supply the same passphrase you used when performing ''luksFormat'' above.
  
 <code bash> <code bash>
-cryptsetup open [encrypted-device] [map-name]+cryptsetup open [encrypted-device] [map-name]
 </code> </code>
  
-Format and mount the (now available) decrypted device.  ''[mount-point]'' is where you want the filesystem mounted (eg. /mnt):+Format and mount the (now available) decrypted device. 
 +''[mount-point]'' is where you want the filesystem mounted (eg. ''/mnt''):
  
 <code bash> <code bash>
-mkfs.ext4 /dev/mapper/[map-name] +mkfs.ext4 /dev/mapper/[map-name] 
-mount /dev/mapper/[map-name] [mount-point]+mount /dev/mapper/[map-name] [mount-point]
 </code> </code>
  
Line 43: Line 48:
  
 <code bash> <code bash>
-cryptsetup open [encrypted-device] [map-name] +cryptsetup open [encrypted-device] [map-name] 
-mount /dev/mapper/[map-name] [mount-point]+mount /dev/mapper/[map-name] [mount-point]
 </code> </code>
  
Line 50: Line 55:
  
 <code bash> <code bash>
-umount [mount-point] +umount [mount-point] 
-cryptsetup close [map-name]+cryptsetup close [map-name]
 </code> </code>
 +
 +Automated:
 +
 +The following script can be used to automate decrypting and mounting removable storage that is encrypted by using entries in ''/etc/crypttab'' (like many linux distros) and ''/etc/config/fstab''. To use the following script, a key-file must be generated. To see the occupied Keyslots in the LUKS device:
 +<code bash>
 +cryptsetup luksDump [encrypted-device]
 +</code>
 +
 +''Keyslots'' should have 1 entry (''0:'', from the passphrase created earlier). To use a previously generated key-file, this step may be omitted. To create a new key-file:
 +<code bash>
 +dd if=/dev/urandom of=[path/to/key-file] bs=512 count=8
 +</code>
 +
 +This will create a key-file that is filled with 4096 bytes of random data. Add this key-file to the LUKS device:
 +<code bash> 
 +cryptsetup luksAddKey [encrypted-device] [path/to/key-file]
 +</code>
 +
 +You will be prompted for the passphrase from above.
 +
 +<code bash>
 +cryptsetup luksDump [encrypted-device]
 +</code>
 +''Keyslots'' should now contain 2 entries (''1:'' correlating to the newly created key-file). The format of ''/etc/crypttab'' should be as follows:
 +''[map-name] [UUID=UUID-of-encrypted-device] [path/to/key-file] [type-of-encryption]''
 +
 +[UUID] and [type-of-encryption] may be obtained from the output of:
 +<code bash>
 +block info
 +</code>
 +
 +''[type-of-encryption]'' must match exactly with ''TYPE='' given by ''block info''.
 +
 +<code bash>
 +cat << "EOF" > /etc/hotplug.d/block/99-lukscrypt
 +# note: this needs ash and awk installed
 +ash /bin/decrypt.sh
 +EOF
 +
 +cat << "EOF" > /bin/decrypt.sh
 +#!/bin/ash
 +# Perform tasks when called by BLOCK hotplug (/etc/hotplug.d/block/99-lukscrypt)
 +# CC0: 21JUL18 by WaLLy3K, updated 09AUG18
 +# Further adapted for OpenWRT 18.06 by jmm on 2018-09-04
 +# Further apapted for OpenWRT 21.02.2 by mdpc on 2022-12-30
 +
 +# Hotplug Vars: $ACTION (add/remove), $DEVICE (?), $DEVNAME (sdx)
 +
 +# logger -s "start decrypt luks" $DEVNAME $ACTION
 +
 +if [ -z "${DEVNAME}" ]
 +then
 +    DEVNAME="${1##*/}"
 +fi
 +
 +msg() {
 +    logger -st "$(basename "${0%.*}")($DEVNAME)[$$]" -- "$@"
 +}
 +
 +if [ "$ACTION" != "add" ]
 +then
 +    #only do something if a device is being added
 +    exit 0
 +fi
 +
 +if [[ "$DEVNAME" == dm-[0-9] ]]
 +then
 +    #/dev/mapper block device has been created so now try to mount FS if set up
 +    # in /etc/config/fstab (or LuCI > System > Mount Points)
 +    block mount
 +    exit 0
 +fi
 +
 +BID_RAW="$(block info "/dev/$DEVNAME" | awk -v RS=' ' '{gsub("[:\"]",""); print $0}')"
 +BID_UUID="$(echo $BID_RAW | awk -F['/=',' '] '{print $5}')"
 +BID_TYPE="$(echo $BID_RAW | awk -F['/=',' '] '{print $7}')"
 +
 +# Determine whether drive needs to be decrypted
 +if [[ ! -r "/etc/crypttab" ]]
 +then
 +    msg "Unable to read file: /etc/crypttab"
 +    exit 1
 +fi
 +CT_RAW="$(grep "$BID_UUID" /etc/crypttab)"
 +if [[ -z "${CT_RAW:-}" ]]
 +then
 +    exit 0
 +fi
 +
 +CT_LABEL="$(echo $CT_RAW | awk '{print $1}')"
 +CT_KEYFILE="$(echo $CT_RAW | awk '{print $3}')"
 +CT_TYPE="$(echo $CT_RAW | awk -F '[ ,]+' '{print $4}')"
 +
 +if [[ -e "/dev/mapper/${CT_LABEL}" ]]
 +then
 +    msg "Drive already decrypted: $CT_LABEL"
 +    exit 0
 +fi
 +
 +# Error Handling
 +if [[ ! -e "$CT_KEYFILE" ]]
 +then
 +    msg "Unable to view keyfile: '$CT_KEYFILE'"
 +    exit 1
 +fi
 +if [[ ! "${BID_TYPE}" == *"${CT_TYPE}"* ]]
 +then
 +    msg "Unable to decrypt format: $CT_TYPE"
 +    exit 1
 +fi
 +
 +msg "Decrypting drive: $CT_LABEL (/dev/$DEVNAME)"
 +cryptsetup luksOpen "/dev/$DEVNAME" "${CT_LABEL}" -d "$CT_KEYFILE"
 +CS_EXIT="$?"
 +case "$CS_EXIT" in
 +0)  if [ -e "/dev/mapper/${CT_LABEL}" ]
 +    then
 +        msg "Drive decrypted: $CT_LABEL"
 +    else
 +        msg "Drive not found after decrypting: $CT_LABEL"
 +        exit 1
 +    fi;;
 +5)  msg "Device already exists: $CT_LABEL (Dmsetup stuck?)"; exit 1;;
 +*)  msg "Unable to decrypt drive: $CT_LABEL ($CS_EXIT)"; exit 1;;
 +esac
 +EOF
 +</code>
 +
 +The above script does not unmount or remove ''/dev/mapper'' devices when a USB device is removed so this must be done manually as outlined above.
  
 ===== Example ===== ===== Example =====
 A video demonstration on OpenWrt 14.07 Barrier Breaker using LUKS: [[https://www.youtube.com/watch?v=NSVWb6dscVI]] (broken link, 07.Mar.2016) A video demonstration on OpenWrt 14.07 Barrier Breaker using LUKS: [[https://www.youtube.com/watch?v=NSVWb6dscVI]] (broken link, 07.Mar.2016)
 +
  • Last modified: 2023/07/24 23:25
  • by crass