1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
.TH DM-NUKE 1 "March 2025" "v1.3" "System Administration"
.SH NAME
dm-nuke \- Smart decryption mkinitcpio hook with Nuke password and decryption from file.
.SH DESCRIPTION
The
.B dm-nuke
hook is a mkinitcpio hook that assists with LUKS device decryption. It can retrieve the decryption password from a specified file or block device. If no password is found, it will prompt for interactive password entry. If the "nuke" password is provided, the hook will destroy the LUKS headers, making the encrypted data unrecoverable.
The hook is configured via the kernel command line with a single argument:
.BR dm-nuke .
This argument is passed as a CSV string containing various options.
To activate the hook, replace the "encrypt" hook with "dm-crypt" in
.I /etc/mkinitcpio.conf .
.SH SUPPORTED KEY FETCHING MECHANISMS
.TP
.B keyfile
Retrieve the key from a file or block device. The key may also be stored on a volume, which will be temporarily mounted for retrieval.
.TP
.B keyscript
Execute a custom script whose stdout will be treated as the key. The script can reside on an external volume like a keyfile. It is executed within its directory.
.TP
.B interactive
Prompt for interactive user password input.
.SH REQUIRED CONFIGURATION
The following option must be specified in the kernel argument.
.TP
.B device=<block-device-selector>
Device identifier. Refer to
.BR mount (8)
for supported options (e.g., UUID, LABEL). Example:
.B UUID=42da0235-9ceb-4422-a5e4-c6f2011d6bf9 .
.SH OPTIONAL CONFIGURATION
The following options are optional.
.TP
.B alias=<alias>
Alias for the encrypted device as it will appear under
.I /dev/mapper/<alias> .
If unset, defaults to "cryptroot".
.B Note:
Ensure this matches the value set for the
.B root
kernel argument.
.TP
.B cryptargs=<cli-options>
Additional options passed to
.BR cryptsetup (1)
luksOpen during mounting.
.TP
.B keyfile-root=<block-device-selector>:<fstype>
If the keyfile is on an external device, it must be mounted. The
.I <block-device-selector>
follows the same format as the
.B device
option. The filesystem type must be specified for
.BR mount (8) .
To enable automatic detection, set
.I <fstype>
to
.B auto .
If
.B keyfile-root
is specified,
.B keyfile-path
becomes mandatory.
.B Note:
Ensure required filesystem modules are listed in MODULES in
.I /etc/mkinitcpio.conf .
See
.BR mkinitcpio.conf (5) .
.TP
.B keyfile-path=<path>
Path to the keyfile relative to
.B keyfile-root
(if set). The path can also point to a block device (e.g.,
.I /dev/disk/by-id/*
) for direct raw byte reading.
.TP
.B keyfile-offset=<offset>
Byte offset within the keyfile where the password starts. Useful for large keyfiles or block devices with embedded passwords.
.TP
.B keyfile-size=<size>
Number of bytes to read from the keyfile.
.TP
.B keyscript-root=<block-device-selector>:<fstype>
Same as
.B keyfile-root
but for keyscript.
.TP
.B keyscript-path=<path>
Same as
.B keyfile-path
but for keyscript.
.TP
.B nuke=<password-hash>
The
.B hash
of the nuke password used to destroy LUKS headers. Supported hash algorithms: MD5, SHA1, SHA256, SHA512. If the provided password matches the hash, the hook erases the headers, making the data unrecoverable. Generate a hash using:
.BR md5sum (1) ,
.BR sha1sum (1) ,
.BR sha256sum (1) ,
or
.BR sha512sum (1) .
When triggered, an ASCII nuclear explosion animation is displayed unless the "quiet" kernel argument is set.
.SH EXAMPLES
To use the
.B dm-nuke
hook, add the following kernel arguments to the bootloader configuration (e.g., GRUB:
.I /etc/default/grub ).
.TP
Decryption to
.I /dev/mapper/cryptroot
with interactive input only.
.nf
dm-nuke=device=LABEL=luks-root root=/dev/mapper/cryptroot
.fi
.TP
Decryption to
.I /dev/mapper/myroot
with interactive input only.
.nf
dm-nuke=device=LABEL=luks-root,alias=myroot root=/dev/mapper/myroot
.fi
.TP
Keyfile from a raw device with a specific key offset and length (otherwise, the entire device is read).
.nf
dm-nuke=device=LABEL=luks-root,keyfile-path=/dev/disk/by-label/key-device,keyfile-offset=1234,keyfile-size=5678 root=/dev/mapper/cryptroot
.fi
.TP
Keyfile from a raw device with a fallback keyscript. The first valid key found will be used.
.nf
dm-nuke=device=LABEL=luks-root,keyfile-path=/dev/disk/by-label/key-device,keyfile-offset=1234,keyfile-size=5678,keyscript-root=LABEL=my-boot-partition,keyscript-path=/get-from-yubico.sh root=/dev/mapper/cryptroot
.fi
.TP
Interactive input with a nuke password (MD5 hash of "kaboom"). The nuke password applies to interactive input only.
.nf
dm-nuke=device=LABEL=luks-root,nuke=5d9e554a79279cd6dd708dd6e65e3e8 root=/dev/mapper/cryptroot
.fi
|