luksmeta.8.adoc 9.3 KB

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