Browse Source

Merge upstream version 9

Christoph Biedl 1 year ago
parent
commit
ef7140a915
14 changed files with 362 additions and 259 deletions
  1. 17 3
      Makefile.am
  2. 24 6
      Makefile.in
  3. 1 1
      compile
  4. 1 1
      config.guess
  5. 1 1
      config.sub
  6. 74 10
      configure
  7. 9 1
      configure.ac
  8. 1 1
      depcomp
  9. 2 0
      libluksmeta.c
  10. 3 1
      ltmain.sh
  11. 0 232
      luksmeta.8
  12. 227 0
      luksmeta.8.adoc
  13. 1 1
      missing
  14. 1 1
      test-driver

+ 17 - 3
Makefile.am

@@ -1,5 +1,6 @@
 AM_CFLAGS = @LUKSMETA_CFLAGS@ @cryptsetup_CFLAGS@
-
+BUILT_SOURCES=
+CLEANFILES=
 noinst_LTLIBRARIES = libcrc32c.la
 libcrc32c_la_SOURCES = crc32c.c crc32c.h
 
@@ -10,8 +11,22 @@ libluksmeta_la_LIBADD = libcrc32c.la @cryptsetup_LIBS@
 
 bin_PROGRAMS = luksmeta
 luksmeta_LDADD = libluksmeta.la @cryptsetup_LIBS@
+man_ADOC_FILES = luksmeta.8.adoc
+
+if HAVE_A2X
+man_ROFF_FILES = $(man_ADOC_FILES:.adoc=.roff)
+BUILT_SOURCES += $(man_ROFF_FILES)
+CLEANFILES += $(man_ROFF_FILES) $(man_ROFF_FILES:.roff=)
+
+$(top_builddir)/%.roff: %.adoc
+	$(MKDIR_P) $$(dirname $@)
+	$(A2X) -v -f manpage $^ -D $(top_builddir)/$$(dirname $@)
+	$(INSTALL) -m 644 $(top_builddir)/$(@:.roff=) $(top_builddir)/$@
 
 man8_MANS = luksmeta.8
+else
+man8_MANS =
+endif
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = luksmeta.pc
@@ -27,6 +42,5 @@ test_lm_one_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 test_lm_two_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 test_lm_big_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 
-EXTRA_DIST = $(man8_MANS) test-luksmeta
+EXTRA_DIST = $(man_ADOC_FILES) test-luksmeta
 TESTS = $(check_PROGRAMS) test-luksmeta
-

+ 24 - 6
Makefile.in

@@ -93,6 +93,8 @@ build_triplet = @build@
 host_triplet = @host@
 target_triplet = @target@
 bin_PROGRAMS = luksmeta$(EXEEXT)
+@HAVE_A2X_TRUE@am__append_1 = $(man_ROFF_FILES)
+@HAVE_A2X_TRUE@am__append_2 = $(man_ROFF_FILES) $(man_ROFF_FILES:.roff=)
 check_PROGRAMS = test-crc32c$(EXEEXT) test-lm-assumptions$(EXEEXT) \
 	test-lm-init$(EXEEXT) test-lm-one$(EXEEXT) \
 	test-lm-two$(EXEEXT) test-lm-big$(EXEEXT)
@@ -446,6 +448,7 @@ distuninstallcheck_listfiles = find . -type f -print
 am__distuninstallcheck_listfiles = $(distuninstallcheck_listfiles) \
   | sed 's|^\./|$(prefix)/|' | grep -v '$(infodir)/dir$$'
 distcleancheck_listfiles = find . -type f -print
+A2X = @A2X@
 ACLOCAL = @ACLOCAL@
 AMTAR = @AMTAR@
 AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
@@ -572,6 +575,8 @@ top_build_prefix = @top_build_prefix@
 top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 AM_CFLAGS = @LUKSMETA_CFLAGS@ @cryptsetup_CFLAGS@
+BUILT_SOURCES = $(am__append_1)
+CLEANFILES = $(am__append_2)
 noinst_LTLIBRARIES = libcrc32c.la
 libcrc32c_la_SOURCES = crc32c.c crc32c.h
 include_HEADERS = luksmeta.h
@@ -579,7 +584,10 @@ lib_LTLIBRARIES = libluksmeta.la
 libluksmeta_la_LDFLAGS = -export-symbols-regex '^luksmeta_'
 libluksmeta_la_LIBADD = libcrc32c.la @cryptsetup_LIBS@
 luksmeta_LDADD = libluksmeta.la @cryptsetup_LIBS@
-man8_MANS = luksmeta.8
+man_ADOC_FILES = luksmeta.8.adoc
+@HAVE_A2X_TRUE@man_ROFF_FILES = $(man_ADOC_FILES:.adoc=.roff)
+@HAVE_A2X_FALSE@man8_MANS = 
+@HAVE_A2X_TRUE@man8_MANS = luksmeta.8
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = luksmeta.pc
 check_LTLIBRARIES = libtest.la
@@ -590,9 +598,10 @@ test_lm_init_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 test_lm_one_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 test_lm_two_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
 test_lm_big_LDADD = libtest.la libluksmeta.la @cryptsetup_LIBS@
-EXTRA_DIST = $(man8_MANS) test-luksmeta
+EXTRA_DIST = $(man_ADOC_FILES) test-luksmeta
 TESTS = $(check_PROGRAMS) test-luksmeta
-all: all-am
+all: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) all-am
 
 .SUFFIXES:
 .SUFFIXES: .c .lo .log .o .obj .test .test$(EXEEXT) .trs
@@ -1346,7 +1355,8 @@ distcleancheck: distclean
 check-am: all-am
 	$(MAKE) $(AM_MAKEFLAGS) $(check_LTLIBRARIES) $(check_PROGRAMS)
 	$(MAKE) $(AM_MAKEFLAGS) check-TESTS
-check: check-am
+check: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) check-am
 all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(MANS) $(DATA) $(HEADERS)
 install-binPROGRAMS: install-libLTLIBRARIES
 
@@ -1354,7 +1364,8 @@ installdirs:
 	for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man8dir)" "$(DESTDIR)$(pkgconfigdir)" "$(DESTDIR)$(includedir)"; do \
 	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 	done
-install: install-am
+install: $(BUILT_SOURCES)
+	$(MAKE) $(AM_MAKEFLAGS) install-am
 install-exec: install-exec-am
 install-data: install-data-am
 uninstall: uninstall-am
@@ -1379,6 +1390,7 @@ mostlyclean-generic:
 	-test -z "$(TEST_SUITE_LOG)" || rm -f $(TEST_SUITE_LOG)
 
 clean-generic:
+	-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
 
 distclean-generic:
 	-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
@@ -1387,6 +1399,7 @@ distclean-generic:
 maintainer-clean-generic:
 	@echo "This command is intended for maintainers to use"
 	@echo "it deletes files that may require special tools to rebuild."
+	-test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES)
 clean: clean-am
 
 clean-am: clean-binPROGRAMS clean-checkLTLIBRARIES clean-checkPROGRAMS \
@@ -1466,7 +1479,7 @@ uninstall-am: uninstall-binPROGRAMS uninstall-includeHEADERS \
 
 uninstall-man: uninstall-man8
 
-.MAKE: check-am install-am install-strip
+.MAKE: all check check-am install install-am install-strip
 
 .PHONY: CTAGS GTAGS TAGS all all-am am--refresh check check-TESTS \
 	check-am clean clean-binPROGRAMS clean-checkLTLIBRARIES \
@@ -1494,6 +1507,11 @@ uninstall-man: uninstall-man8
 .PRECIOUS: Makefile
 
 
+@HAVE_A2X_TRUE@$(top_builddir)/%.roff: %.adoc
+@HAVE_A2X_TRUE@	$(MKDIR_P) $$(dirname $@)
+@HAVE_A2X_TRUE@	$(A2X) -v -f manpage $^ -D $(top_builddir)/$$(dirname $@)
+@HAVE_A2X_TRUE@	$(INSTALL) -m 644 $(top_builddir)/$(@:.roff=) $(top_builddir)/$@
+
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
 .NOEXPORT:

+ 1 - 1
compile

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # Wrapper for compilers which do not understand '-c -o'.
 
 scriptversion=2016-01-11.22; # UTC

+ 1 - 1
config.guess

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # Attempt to guess a canonical system name.
 #   Copyright 1992-2017 Free Software Foundation, Inc.
 

+ 1 - 1
config.sub

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # Configuration validation subroutine script.
 #   Copyright 1992-2017 Free Software Foundation, Inc.
 

+ 74 - 10
configure

@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for luksmeta 8.
+# Generated by GNU Autoconf 2.69 for luksmeta 9.
 #
 #
 # Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc.
@@ -587,8 +587,8 @@ MAKEFLAGS=
 # Identity of this package.
 PACKAGE_NAME='luksmeta'
 PACKAGE_TARNAME='luksmeta'
-PACKAGE_VERSION='8'
-PACKAGE_STRING='luksmeta 8'
+PACKAGE_VERSION='9'
+PACKAGE_STRING='luksmeta 9'
 PACKAGE_BUGREPORT=''
 PACKAGE_URL=''
 
@@ -632,6 +632,9 @@ ac_subst_vars='am__EXEEXT_FALSE
 am__EXEEXT_TRUE
 LTLIBOBJS
 LIBOBJS
+HAVE_A2X_FALSE
+HAVE_A2X_TRUE
+A2X
 LUKSMETA_CFLAGS
 cryptsetup_LIBS
 cryptsetup_CFLAGS
@@ -1324,7 +1327,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures luksmeta 8 to adapt to many kinds of systems.
+\`configure' configures luksmeta 9 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1395,7 +1398,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of luksmeta 8:";;
+     short | recursive ) echo "Configuration of luksmeta 9:";;
    esac
   cat <<\_ACEOF
 
@@ -1514,7 +1517,7 @@ fi
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-luksmeta configure 8
+luksmeta configure 9
 generated by GNU Autoconf 2.69
 
 Copyright (C) 2012 Free Software Foundation, Inc.
@@ -1792,7 +1795,7 @@ cat >config.log <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by luksmeta $as_me 8, which was
+It was created by luksmeta $as_me 9, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   $ $0 $@
@@ -3855,7 +3858,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='luksmeta'
- VERSION='8'
+ VERSION='9'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -12347,6 +12350,63 @@ LUKSMETA_CFLAGS="\
 "
 
 
+for ac_prog in a2x
+do
+  # Extract the first word of "$ac_prog", so it can be a program name with args.
+set dummy $ac_prog; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_A2X+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$A2X"; then
+  ac_cv_prog_A2X="$A2X" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_A2X="$ac_prog"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+fi
+fi
+A2X=$ac_cv_prog_A2X
+if test -n "$A2X"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $A2X" >&5
+$as_echo "$A2X" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+  test -n "$A2X" && break
+done
+
+
+if test "x$A2X" = "x"; then
+   { $as_echo "$as_me:${as_lineno-$LINENO}: WARNING: asciidoc / a2x not found -- man pages will not be generated and installed!" >&5
+$as_echo "$as_me: WARNING: asciidoc / a2x not found -- man pages will not be generated and installed!" >&2;}
+fi
+
+ if test -n "$A2X"; then
+  HAVE_A2X_TRUE=
+  HAVE_A2X_FALSE='#'
+else
+  HAVE_A2X_TRUE='#'
+  HAVE_A2X_FALSE=
+fi
+
+
 ac_config_files="$ac_config_files luksmeta.pc Makefile"
 
 cat >confcache <<\_ACEOF
@@ -12518,6 +12578,10 @@ else
   am__EXEEXT_FALSE=
 fi
 
+if test -z "${HAVE_A2X_TRUE}" && test -z "${HAVE_A2X_FALSE}"; then
+  as_fn_error $? "conditional \"HAVE_A2X\" was never defined.
+Usually this means the macro was only invoked conditionally." "$LINENO" 5
+fi
 
 : "${CONFIG_STATUS=./config.status}"
 ac_write_fail=0
@@ -12915,7 +12979,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by luksmeta $as_me 8, which was
+This file was extended by luksmeta $as_me 9, which was
 generated by GNU Autoconf 2.69.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -12972,7 +13036,7 @@ _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-luksmeta config.status 8
+luksmeta config.status 9
 configured by $0, generated by GNU Autoconf 2.69,
   with options \\"\$ac_cs_config\\"
 

+ 9 - 1
configure.ac

@@ -1,5 +1,5 @@
 AC_PREREQ(2.59)
-AC_INIT(luksmeta, 8)
+AC_INIT(luksmeta, 9)
 AC_CANONICAL_SYSTEM
 AC_PROG_CC_C99
 
@@ -33,5 +33,13 @@ LUKSMETA_CFLAGS="\
 "
 AC_SUBST([LUKSMETA_CFLAGS])
 
+AC_CHECK_PROGS(A2X, [a2x])
+
+if test "x$A2X" = "x"; then
+   AC_MSG_WARN([asciidoc / a2x not found -- man pages will not be generated and installed!])
+fi
+
+AM_CONDITIONAL(HAVE_A2X, [test -n "$A2X"])
+
 AC_CONFIG_FILES([luksmeta.pc Makefile])
 AC_OUTPUT

+ 1 - 1
depcomp

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # depcomp - compile a program generating dependencies as side-effects
 
 scriptversion=2016-01-11.22; # UTC

+ 2 - 0
libluksmeta.c

@@ -119,6 +119,8 @@ readall(int fd, void *data, size_t size)
         r = read(fd, &tmp[t], size - t);
         if (r < 0 && errno != EAGAIN)
             return -errno;
+        if (r == 0)
+            return -ENOENT;
     }
 
     return size;

+ 3 - 1
ltmain.sh

@@ -7272,10 +7272,12 @@ func_mode_link ()
       # -tp=*                Portland pgcc target processor selection
       # --sysroot=*          for sysroot support
       # -O*, -g*, -flto*, -fwhopr*, -fuse-linker-plugin GCC link-time optimization
+      # -specs=*             GCC specs files
       # -stdlib=*            select c++ std lib with clang
       -64|-mips[0-9]|-r[0-9][0-9]*|-xarch=*|-xtarget=*|+DA*|+DD*|-q*|-m*| \
       -t[45]*|-txscale*|-p|-pg|--coverage|-fprofile-*|-F*|@*|-tp=*|--sysroot=*| \
-      -O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*)
+      -O*|-g*|-flto*|-fwhopr*|-fuse-linker-plugin|-fstack-protector*|-stdlib=*| \
+      -specs=*)
         func_quote_for_eval "$arg"
 	arg=$func_quote_for_eval_result
         func_append compile_command " $arg"

File diff suppressed because it is too large
+ 0 - 232
luksmeta.8


+ 227 - 0
luksmeta.8.adoc

@@ -0,0 +1,227 @@
+luksmeta(8)
+===========
+:doctype: manpage
+
+== 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>
+
+== SEE ALSO
+
+*cryptsetup*(8),
+*uuidgen*(1)

+ 1 - 1
missing

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # Common wrapper for a few potentially missing GNU programs.
 
 scriptversion=2016-01-11.22; # UTC

+ 1 - 1
test-driver

@@ -1,4 +1,4 @@
-#! /bin/sh
+#!/bin/sh
 # test-driver - basic testsuite driver script.
 
 scriptversion=2016-01-11.22; # UTC