Ubuntu Manpage: luksmeta - Utility for storing metadata in a LUKSv1 header

NAME

       luksmeta - Utility for storing metadata in a LUKSv1 header

SYNOPSIS

       luksmeta test -d DEVICE

       luksmeta nuke -d DEVICE [-f]

       luksmeta init -d DEVICE [-f] [-n]

       luksmeta show -d DEVICE [-s SLOT]

       luksmeta save -d DEVICE [-s SLOT] -u UUID DATA

       luksmeta load -d DEVICE -s SLOT [-u UUID] DATA

       luksmeta wipe -d DEVICE -s SLOT [-u UUID] [-f]

OVERVIEW

       The  luksmeta utility enables an administrator to store metadata in the gap between the end of the LUKSv1
       header and the start of the encrypted data. This is useful for storing data that is available before  the
       volume is unlocked, usually for use during the volume unlock process.

       The  metadata  is  stored in a series of UUID-typed slots, allowing multiple blocks of metadata. Although
       the luksmeta slots are inspired by the LUKS slots, they are functionally independent  and  share  only  a
       casual  relationship.  Slots  merely  provide  a hint that a given chunk of metadata is associated with a
       specific LUKSv1 password (in a slot with the same number). However, luksmeta itself is indifferent to the
       relationship  between  a  LUKSv1  slot  and  the  correspondly numbered luksmeta slot, with one exception
       (detailed below).

       After a LUKSv1 volume is initialized using cryptsetup(8),  it  must  also  be  initialized  for  metadata
       storage by luksmeta init. Once this is complete, the device is ready to store medata.

       Data  can  be written to a slot using luksmeta save or read from a slot using luksmeta load. You can also
       erase the data in an existing slot using luksmeta wipe or query the slots using luksmeta show.

UUID GENERATION

       It is often presumed that saving metadata to a slot requires a specific UUID or that there is an official
       registry of UUID types. This is incorrect.

       UUID  stands  for Universally Unique IDentifier. UUIDs are a standardized, widely-used data type used for
       identification without a central registry. For the relevant standards, see ISO 9834-8:2005 and RFC 4122.

       UUIDs are large enough that collision is practically impossible. So if your application  wants  to  store
       data  in  a  luksmeta  slot, just generate your own UUID and use it consistently to refer to your type of
       data. If you have multiple types of data, feel free to generate multiple UUIDs.

       The easiest way to generate a UUID is to use uuidgen(1).  However,  any  compliant  UUID  generator  will
       suffice.

INITIALIZATION

       Before  reading  or  writing  metadata, the LUKSv1 block device must be initialized for metadata storage.
       Three commands help with this process: luksmeta test, luksmeta nuke and luksmeta init.

       The luksmeta test command simply checks an existing block device to see if it is initialized for metadata
       storage. This command does not provide any output, so be sure to check its return code (see below).

       The  luksmeta  nuke  command  will  zero  (erase)  the  entire LUKSv1 header gap. Since this operation is
       destructive, user confirmation will be required before clearing the gap unless the -f option is supplied.

       The luksmeta init command initializes the LUKSv1 block device for metadata  storage.  This  process  will
       wipe  out any data in the LUKSv1 header gap. For this reason, this command will require user confirmation
       before any data is written unless the -f option is supplied. Note that this command succeeds without  any
       modification  if  the  device  is  already  initialized. If you would like to force the creation of clean
       initialization state, you can specify the -n option to nuke the LUKSv1 header gap  before  initialization
       (but after user confirmation).

METADATA STATE

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

MANAGING METADATA

Managing the metadata in the slots is performed with three commands: luksmeta save, luksmeta load and
luksmeta wipe. These commands write metadata to a slot, read metadata from a slot and erase metadata in a
slot, respectively.

The luksmeta save command reads metadata on standard input and writes it to the specified slot using the
specified UUID. If no slot is specified, luksmeta will search for the first slot number for which the
LUKSv1 slot is inactive and the luksmeta slot is empty. This represents the only official correlation
between LUKSv1 slots and luksmeta slots. In this case, the metadata is written to the first applicable
slot using the specified UUID and the slot number is printed to standard output. In either case, this
command will never overwrite existing data. To replace data in a slot you will need to execute luksmeta
wipe before luksmeta save.

The luksmeta load command reads data from the specified slot and writes it to standard output. If a UUID
is specified, the command will verify that the UUID associated with the metadata in the slot matches the
specified UUID. This type check helps to ensure that you always receive the type of data you are
expecting as output. If the UUIDs do not match, the command will fail.

The luksmeta wipe command erases the data from the given slot. If a UUID is specified, the command will
verify that the UUID associated with the metadata in the slot matches the specified UUID. This type check
helps to ensure that you only erase the data you intended to erase. Because this is a destructive
operation, this command will require user confirmation before any data is erased, unless the -f option is
supplied. Note that this command succeeds if you attempt to wipe a slot that is already empty.

CAVEATS

The amount of storage in the LUKSv1 header gap is extremely limited. It also varies based upon the
configuration used by LUKSv1 at device initialization time. In some LUKSv1 configurations, there is not
even enough space for all the metadata slots even at the smallest possible slot size.

During the design of this utility, we considered it likely that users would want to reduce the number of
usable slots in exchange for more storage space in the slots used. In order to provide this flexibility,
the amount of storage available per-slot is dynamic. Put simply, slots are not a fixed size. This means
that it is possible (and even somewhat likely) to encounter an error during luksmeta save indicating that
there is insufficient space.

This error is not a programming bug. If you encounter this error it likely means that either all space is
being consumed by the already-written slots or that the metadata you are attempting to write simply does
not fit.

You can attempt to resolve this problem by calling luksmeta wipe on slots that are no longer in use. This
will release the storage space for use by other slots. Note that luksmeta does not, however, currently
perform defragmentation since the number of usable blocks is rather limited. You can attempt to manually
get around this by extracting all slot data, wiping the slots and reloading them in order. However, this
operation is potentially dangerous and should be undertaken with great care.

OPTIONS

       -d DEVICE, --device=DEVICE
              The device on which to perform the operation.

       -s SLOT, --slot=SLOT
              The slot number on which to perform the operation.

       -u UUID, --uuid=UUID
              The UUID to associate with the operation.

       -f, --force
              Forcibly suppress all user prompting.

RETURN VALUES

       This command uses the return values as defined by sysexit.h.  The  following  are  general  errors  whose
       meaning is shared by all luksmeta commands:

       •   EX_OK : The operation was successful.

       •   EX_OSERR : An undefined operating system error occurred.

       •   EX_USAGE : The program was called with invalid parameters.

       •   EX_IOERR : An IO error occurred when writing to the device.

       •   EX_OSFILE : The device is not initialized or is corrupted.

       •   EX_NOPERM : The user did not grant permission during confirmation.

       •   EX_NOINPUT : An error occurred while reading from standard input.

       •   EX_DATAERR : The specified UUID does not match the slot UUID.

       •   EX_CANTCREAT : There is insufficient space in LUKSv1 header.

       Additionally,  luksmeta save will return EX_UNAVAILABLE when you attempt to save data into a slot that is
       already used. Likewise, luksmeta load will return EX_UNAVAILABLE when you attempt to read from  an  empty
       slot.

EXAMPLES

       Destroy  all  data (including LUKSMeta data) in the LUKSv1 header gap and initialize the gap for LUKSMeta
       storage:

           $ luksmeta init -n -f -d /dev/sdz

       If already initialized, do nothing. Otherwise, destroy all non-LUKSMeta data in the LUKSv1 header gap and
       initialize the gap for LUKSMeta storage:

           $ luksmeta init -f -d /dev/sdz

       Write some data to a slot:

           $ UUID=`uuidgen`
           $ echo $UUID
           31c25e3b-b8e2-4eaa-a427-23aa882feef2
           $ echo "Hello, World" | luksmeta save -d /dev/sdz -s 0 -u $UUID

       Read the data back:

           $ luksmeta load -d /dev/sdz -s 0 -u $UUID
           Hello, World

       Wipe the data from the slot:

           $ luksmeta wipe -d /dev/sdz -s 0 -u $UUID

       Erase all trace of LUKSMeta:

           $ luksmeta nuke -f -d /dev/sdz

AUTHOR

       Nathaniel McCallum <npmccallum@redhat.com>