1LUKSMETA(1)                                                        LUKSMETA(1)
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 vol‐
27       ume is unlocked, usually for use during the volume unlock process.
28
29       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
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 com‐
40       plete, 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 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
55       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
60       The easiest way to generate a UUID is to use uuidgen(1).  However,  any
61       compliant UUID generator will suffice.
62

INITIALIZATION

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
68       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
72       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
76       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

METADATA STATE

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

MANAGING METADATA

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
100       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
111       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
118       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

CAVEATS

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
134       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
142       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
147       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

OPTIONS

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

RETURN VALUES

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
174       ·   EX_OK : The operation was successful.
175
176       ·   EX_OSERR : An undefined operating system error occurred.
177
178       ·   EX_USAGE : The program was called with invalid parameters.
179
180       ·   EX_IOERR : An IO error occurred when writing to the device.
181
182       ·   EX_OSFILE : The device is not initialized or is corrupted.
183
184       ·   EX_NOPERM : The user did not grant permission during confirmation.
185
186       ·   EX_NOINPUT : An error occured while reading from standard input.
187
188       ·   EX_DATAERR : The specified UUID does not match the slot UUID.
189
190       ·   EX_CANTCREAT : There is insufficient space in LUKSv1 header.
191
192
193
194       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

EXAMPLES

199       Destroy all data (including LUKSMeta data) in the LUKSv1 header gap and
200       initalize the gap for LUKSMeta storage:
201
202
203
204           $ luksmeta init -n -f -d /dev/sdz
205
206
207
208       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
212
213
214           $ luksmeta init -f -d /dev/sdz
215
216
217
218       Write some data to a slot:
219
220
221
222           $ 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
227
228
229       Read the data back:
230
231
232
233           $ luksmeta load -d /dev/sdz -s 0 -u $UUID
234           Hello, World
235
236
237
238       Wipe the data from the slot:
239
240
241
242           $ luksmeta wipe -d /dev/sdz -s 0 -u $UUID
243
244
245
246       Erase all trace of LUKSMeta:
247
248
249
250           $ luksmeta nuke -f -d /dev/sdz
251
252
253

AUTHOR

255       Nathaniel McCallum <npmccallum@redhat.com>
256

SEE ALSO

258       cryptsetup(8), uuidgen(1)
259
260
261
262                                   June 2017                       LUKSMETA(1)
Impressum