1LUKSMETA(8)                                                        LUKSMETA(8)
2
3
4

NAME

6       luksmeta - Utility for storing metadata in a LUKSv1 header
7

SYNOPSIS

9       luksmeta test -d DEVICE
10
11       luksmeta nuke -d DEVICE [-f]
12
13       luksmeta init -d DEVICE [-f] [-n]
14
15       luksmeta show -d DEVICE [-s SLOT]
16
17       luksmeta save -d DEVICE [-s SLOT] -u UUID < DATA
18
19       luksmeta load -d DEVICE -s SLOT [-u UUID] > DATA
20
21       luksmeta wipe -d DEVICE -s SLOT [-u UUID] [-f]
22

OVERVIEW

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
27       volume is unlocked, usually for use during the volume unlock process.
28
29       The metadata is stored in a series of UUID-typed slots, allowing
30       multiple blocks of metadata. Although the luksmeta slots are inspired
31       by the LUKS slots, they are functionally independent and share only a
32       casual relationship. Slots merely provide a hint that a given chunk of
33       metadata is associated with a specific LUKSv1 password (in a slot with
34       the same number). However, luksmeta itself is indifferent to the
35       relationship between a LUKSv1 slot and the correspondly numbered
36       luksmeta slot, with one exception (detailed below).
37
38       After a LUKSv1 volume is initialized using cryptsetup(8), it must also
39       be initialized for metadata storage by luksmeta init. Once this is
40       complete, the device is ready to store medata.
41
42       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

UUID GENERATION

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
51       UUID stands for Universally Unique IDentifier. UUIDs are a
52       standardized, widely-used data type used for identification without a
53       central registry. For the relevant standards, see ISO 9834-8:2005 and
54       RFC 4122.
55
56       UUIDs are large enough that collision is practically impossible. So if
57       your application wants to store data in a luksmeta slot, just generate
58       your own UUID and use it consistently to refer to your type of data. If
59       you have multiple types of data, feel free to generate multiple UUIDs.
60
61       The easiest way to generate a UUID is to use uuidgen(1). However, any
62       compliant UUID generator will suffice.
63

INITIALIZATION

65       Before reading or writing metadata, the LUKSv1 block device must be
66       initialized for metadata storage. Three commands help with this
67       process: luksmeta test, luksmeta nuke and luksmeta init.
68
69       The luksmeta test command simply checks an existing block device to see
70       if it is initialized for metadata storage. This command does not
71       provide any output, so be sure to check its return code (see below).
72
73       The luksmeta nuke command will zero (erase) the entire LUKSv1 header
74       gap. Since this operation is destructive, user confirmation will be
75       required before clearing the gap unless the -f option is supplied.
76
77       The luksmeta init command initializes the LUKSv1 block device for
78       metadata storage. This process will wipe out any data in the LUKSv1
79       header gap. For this reason, this command will require user
80       confirmation before any data is written unless the -f option is
81       supplied. Note that this command succeeds without any modification if
82       the device is already initialized. If you would like to force the
83       creation of clean initialization state, you can specify the -n option
84       to nuke the LUKSv1 header gap before initialization (but after user
85       confirmation).
86

METADATA STATE

88       The luksmeta show command displays the current state of slots on the
89       LUKSv1 block device. If no slot is specified, it prints a table
90       consisting of the slot number, the corresponding LUKSv1 slot state and
91       the UUID of the data stored in the luksmeta slot (or "empty" if no data
92       is stored). If a slot is specified, this command simply prints out the
93       UUID of the data in the slot. If the slot does not contain data, it
94       prints nothing.
95

MANAGING METADATA

97       Managing the metadata in the slots is performed with three commands:
98       luksmeta save, luksmeta load and luksmeta wipe. These commands write
99       metadata to a slot, read metadata from a slot and erase metadata in a
100       slot, respectively.
101
102       The luksmeta save command reads metadata on standard input and writes
103       it to the specified slot using the specified UUID. If no slot is
104       specified, luksmeta will search for the first slot number for which the
105       LUKSv1 slot is inactive and the luksmeta slot is empty. This represents
106       the only official correlation between LUKSv1 slots and luksmeta slots.
107       In this case, the metadata is written to the first applicable slot
108       using the specified UUID and the slot number is printed to standard
109       output. In either case, this command will never overwrite existing
110       data. To replace data in a slot you will need to execute luksmeta wipe
111       before luksmeta save.
112
113       The luksmeta load command reads data from the specified slot and writes
114       it to standard output. If a UUID is specified, the command will verify
115       that the UUID associated with the metadata in the slot matches the
116       specified UUID. This type check helps to ensure that you always receive
117       the type of data you are expecting as output. If the UUIDs do not
118       match, the command will fail.
119
120       The luksmeta wipe command erases the data from the given slot. If a
121       UUID is specified, the command will verify that the UUID associated
122       with the metadata in the slot matches the specified UUID. This type
123       check helps to ensure that you only erase the data you intended to
124       erase. Because this is a destructive operation, this command will
125       require user confirmation before any data is erased, unless the -f
126       option is supplied. Note that this command succeeds if you attempt to
127       wipe a slot that is already empty.
128

CAVEATS

130       The amount of storage in the LUKSv1 header gap is extremely limited. It
131       also varies based upon the configuration used by LUKSv1 at device
132       initialization time. In some LUKSv1 configurations, there is not even
133       enough space for all the metadata slots even at the smallest possible
134       slot size.
135
136       During the design of this utility, we considered it likely that users
137       would want to reduce the number of usable slots in exchange for more
138       storage space in the slots used. In order to provide this flexibility,
139       the amount of storage available per-slot is dynamic. Put simply, slots
140       are not a fixed size. This means that it is possible (and even somewhat
141       likely) to encounter an error during luksmeta save indicating that
142       there is insufficient space.
143
144       This error is not a programming bug. If you encounter this error it
145       likely means that either all space is being consumed by the
146       already-written slots or that the metadata you are attempting to write
147       simply does not fit.
148
149       You can attempt to resolve this problem by calling luksmeta wipe on
150       slots that are no longer in use. This will release the storage space
151       for use by other slots. Note that luksmeta does not, however, currently
152       perform defragmentation since the number of usable blocks is rather
153       limited. You can attempt to manually get around this by extracting all
154       slot data, wiping the slots and reloading them in order. However, this
155       operation is potentially dangerous and should be undertaken with great
156       care.
157

OPTIONS

159-d DEVICE, --device=DEVICE : The device on which to perform the
160           operation.
161
162-s SLOT, --slot=SLOT : The slot number on which to perform the
163           operation.
164
165-u UUID, --uuid=UUID : The UUID to associate with the operation.
166
167-f, --force : Forcibly suppress all user prompting.
168

RETURN VALUES

170       This command uses the return values as defined by sysexit.h. The
171       following are general errors whose meaning is shared by all luksmeta
172       commands:
173
174EX_OK : The operation was successful.
175
176EX_OSERR : An undefined operating system error occurred.
177
178EX_USAGE : The program was called with invalid parameters.
179
180EX_IOERR : An IO error occurred when writing to the device.
181
182EX_OSFILE : The device is not initialized or is corrupted.
183
184EX_NOPERM : The user did not grant permission during confirmation.
185
186EX_NOINPUT : An error occurred while reading from standard input.
187
188EX_DATAERR : The specified UUID does not match the slot UUID.
189
190EX_CANTCREAT : There is insufficient space in LUKSv1 header.
191
192       Additionally, luksmeta save will return EX_UNAVAILABLE when you attempt
193       to save data into a slot that is already used. Likewise, luksmeta load
194       will return EX_UNAVAILABLE when you attempt to read from an empty slot.
195

EXAMPLES

197       Destroy all data (including LUKSMeta data) in the LUKSv1 header gap and
198       initialize the gap for LUKSMeta storage:
199
200           $ luksmeta init -n -f -d /dev/sdz
201
202       If already initialized, do nothing. Otherwise, destroy all non-LUKSMeta
203       data in the LUKSv1 header gap and initialize the gap for LUKSMeta
204       storage:
205
206           $ luksmeta init -f -d /dev/sdz
207
208       Write some data to a slot:
209
210           $ UUID=*uuidgen*
211           $ echo $UUID
212           31c25e3b-b8e2-4eaa-a427-23aa882feef2
213           $ echo "Hello, World" | luksmeta save -d /dev/sdz -s 0 -u $UUID
214
215       Read the data back:
216
217           $ luksmeta load -d /dev/sdz -s 0 -u $UUID
218           Hello, World
219
220       Wipe the data from the slot:
221
222           $ luksmeta wipe -d /dev/sdz -s 0 -u $UUID
223
224       Erase all trace of LUKSMeta:
225
226           $ luksmeta nuke -f -d /dev/sdz
227

AUTHOR

229       Nathaniel McCallum <npmccallum@redhat.com>
230

SEE ALSO

232       cryptsetup(8), uuidgen(1)
233
234
235
236                                  07/21/2022                       LUKSMETA(8)
Impressum