1LUKSMETA(1) LUKSMETA(1)
2
6 luksmeta - Utility for storing metadata in a LUKSv1 header
7
9 luksmeta test -d DEVICE
10 luksmeta nuke -d DEVICE [-f]
12 luksmeta init -d DEVICE [-f] [-n]
14 luksmeta show -d DEVICE [-s SLOT]
16 luksmeta save -d DEVICE [-s SLOT] -u UUID DATA
18 luksmeta load -d DEVICE -s SLOT [-u UUID] DATA
20 luksmeta wipe -d DEVICE -s SLOT [-u UUID] [-f]
22
24 The luksmeta utility enables an administrator to store metadata in the
25 gap between the end of the LUKSv1 header and the start of the encrypted
26 data. This is useful for storing data that is available before the vol‐
27 ume is unlocked, usually for use during the volume unlock process.
28 The metadata is stored in a series of UUID-typed slots, allowing multi‐
30 ple blocks of metadata. Although the luksmeta slots are inspired by the
31 LUKS slots, they are functionally independent and share only a casual
32 relationship. Slots merely provide a hint that a given chunk of meta‐
33 data is associated with a specific LUKSv1 password (in a slot with the
34 same number). However, luksmeta itself is indifferent to the relation‐
35 ship between a LUKSv1 slot and the correspondly numbered luksmeta slot,
36 with one exception (detailed below).
37 After a LUKSv1 volume is initialized using cryptsetup(8), it must also
39 be initialized for metadata storage by luksmeta init. Once this is com‐
40 plete, the device is ready to store medata.
41 Data can be written to a slot using luksmeta save or read from a slot
43 using luksmeta load. You can also erase the data in an existing slot
44 using luksmeta wipe or query the slots using luksmeta show.
45
47 It is often presumed that saving metadata to a slot requires a specific
48 UUID or that there is an official registry of UUID types. This is
49 incorrect.
50 UUID stands for Universally Unique IDentifier. UUIDs are a standard‐
52 ized, widely-used data type used for identification without a central
53 registry. For the relevant standards, see ISO 9834-8:2005 and RFC 4122.
54 UUIDs are large enough that collision is practically impossible. So if
56 your application wants to store data in a luksmeta slot, just generate
57 your own UUID and use it consistently to refer to your type of data. If
58 you have multiple types of data, feel free to generate multiple UUIDs.
59 The easiest way to generate a UUID is to use uuidgen(1). However, any
61 compliant UUID generator will suffice.
62
64 Before reading or writing metadata, the LUKSv1 block device must be
65 initialized for metadata storage. Three commands help with this
66 process: luksmeta test, luksmeta nuke and luksmeta init.
67 The luksmeta test command simply checks an existing block device to see
69 if it is initialized for metadata storage. This command does not pro‐
70 vide any output, so be sure to check its return code (see below).
71 The luksmeta nuke command will zero (erase) the entire LUKSv1 header
73 gap. Since this operation is destructive, user confirmation will be
74 required before clearing the gap unless the -f option is supplied.
75 The luksmeta init command initializes the LUKSv1 block device for meta‐
77 data storage. This process will wipe out any data in the LUKSv1 header
78 gap. For this reason, this command will require user confirmation
79 before any data is written unless the -f option is supplied. Note that
80 this command succeeds without any modification if the device is already
81 initialized. If you would like to force the creation of clean initial‐
82 ization state, you can specify the -n option to nuke the LUKSv1 header
83 gap before initialization (but after user confirmation).
84
86 The luksmeta show command displays the current state of slots on the
87 LUKSv1 block device. If no slot is specified, it prints a table con‐
88 sisting of the slot number, the corresponding LUKSv1 slot state and the
89 UUID of the data stored in the luksmeta slot (or "empty" if no data is
90 stored). If a slot is specified, this command simply prints out the
91 UUID of the data in the slot. If the slot does not contain data, it
92 prints nothing.
93
95 Managing the metadata in the slots is performed with three commands:
96 luksmeta save, luksmeta load and luksmeta wipe. These commands write
97 metadata to a slot, read metadata from a slot and erase metadata in a
98 slot, respectively.
99 The luksmeta save command reads metadata on standard input and writes
101 it to the specified slot using the specified UUID. If no slot is speci‐
102 fied, luksmeta will search for the first slot number for which the
103 LUKSv1 slot is inactive and the luksmeta slot is empty. This represents
104 the only official correlation between LUKSv1 slots and luksmeta slots.
105 In this case, the metadata is written to the first applicable slot
106 using the specified UUID and the slot number is printed to standard
107 output. In either case, this command will never overwrite existing
108 data. To replace data in a slot you will need to execute luksmeta wipe
109 before luksmeta save.
110 The luksmeta load command reads data from the specified slot and writes
112 it to standard output. If a UUID is specified, the command will verify
113 that the UUID associated with the metadata in the slot matches the
114 specified UUID. This type check helps to ensure that you always receive
115 the type of data you are expecting as output. If the UUIDs do not
116 match, the command will fail.
117 The luksmeta wipe command erases the data from the given slot. If a
119 UUID is specified, the command will verify that the UUID associated
120 with the metadata in the slot matches the specified UUID. This type
121 check helps to ensure that you only erase the data you intended to
122 erase. Because this is a destructive operation, this command will
123 require user confirmation before any data is erased, unless the -f
124 option is supplied. Note that this command succeeds if you attempt to
125 wipe a slot that is already empty.
126
128 The amount of storage in the LUKSv1 header gap is extremely limited. It
129 also varies based upon the configuration used by LUKSv1 at device ini‐
130 tialization time. In some LUKSv1 configurations, there is not even
131 enough space for all the metadata slots even at the smallest possible
132 slot size.
133 During the design of this utility, we considered it likely that users
135 would want to reduce the number of usable slots in exchange for more
136 storage space in the slots used. In order to provide this flexibility,
137 the amount of storage available per-slot is dynamic. Put simply, slots
138 are not a fixed size. This means that it is possible (and even somewhat
139 likely) to encounter an error during luksmeta save indicating that
140 there is insufficient space.
141 This error is not a programming bug. If you encounter this error it
143 likely means that either all space is being consumed by the
144 already-written slots or that the metadata you are attempting to write
145 simply does not fit.
146 You can attempt to resolve this problem by calling luksmeta wipe on
148 slots that are no longer in use. This will release the storage space
149 for use by other slots. Note that luksmeta does not, however, currently
150 perform defragmentation since the number of usable blocks is rather
151 limited. You can attempt to manually get around this by extracting all
152 slot data, wiping the slots and reloading them in order. However, this
153 operation is potentially dangerous and should be undertaken with great
154 care.
155
157 -d DEVICE, --device=DEVICE
158 The device on which to perform the operation.
159 -s SLOT, --slot=SLOT
161 The slot number on which to perform the operation.
162 -u UUID, --uuid=UUID
164 The UUID to associate with the operation.
165 -f, --force
167 Forcibly suppress all user prompting.
168
170 This command uses the return values as defined by sysexit.h. The fol‐
171 lowing are general errors whose meaning is shared by all luksmeta com‐
172 mands:
173 · EX_OK : The operation was successful.
175 · EX_OSERR : An undefined operating system error occurred.
177 · EX_USAGE : The program was called with invalid parameters.
179 · EX_IOERR : An IO error occurred when writing to the device.
181 · EX_OSFILE : The device is not initialized or is corrupted.
183 · EX_NOPERM : The user did not grant permission during confirmation.
185 · EX_NOINPUT : An error occured while reading from standard input.
187 · EX_DATAERR : The specified UUID does not match the slot UUID.
189 · EX_CANTCREAT : There is insufficient space in LUKSv1 header.
191 Additionally, luksmeta save will return EX_UNAVAILABLE when you attempt
195 to save data into a slot that is already used. Likewise, luksmeta load
196 will return EX_UNAVAILABLE when you attempt to read from an empty slot.
197
199 Destroy all data (including LUKSMeta data) in the LUKSv1 header gap and
200 initalize the gap for LUKSMeta storage:
201 $ luksmeta init -n -f -d /dev/sdz
205 If already initialized, do nothing. Otherwise, destroy all non-LUKSMeta
209 data in the LUKSv1 header gap and initialize the gap for LUKSMeta stor‐
210 age:
211 $ luksmeta init -f -d /dev/sdz
215 Write some data to a slot:
219 $ UUID=`uuidgen`
223 $ echo $UUID
224 31c25e3b-b8e2-4eaa-a427-23aa882feef2
225 $ echo "Hello, World" | luksmeta save -d /dev/sdz -s 0 -u $UUID
226 Read the data back:
230 $ luksmeta load -d /dev/sdz -s 0 -u $UUID
234 Hello, World
235 Wipe the data from the slot:
239 $ luksmeta wipe -d /dev/sdz -s 0 -u $UUID
243 Erase all trace of LUKSMeta:
247 $ luksmeta nuke -f -d /dev/sdz
251
255 Nathaniel McCallum <npmccallum@redhat.com>
256
258 cryptsetup(8), uuidgen(1)
259 June 2017 LUKSMETA(1)