chiark / gitweb /
keyfunc.sh: Fix a couple of messages.
[distorted-keys] / keyfunc.sh.in
index c9cf207..98354d1 100644 (file)
@@ -7,18 +7,20 @@
 
 ###----- Licensing notice ---------------------------------------------------
 ###
-### This program is free software; you can redistribute it and/or modify
+### This file is part of the distorted.org.uk key management suite.
+###
+### distorted-keys is free software; you can redistribute it and/or modify
 ### it under the terms of the GNU General Public License as published by
 ### the Free Software Foundation; either version 2 of the License, or
 ### (at your option) any later version.
 ###
-### This program is distributed in the hope that it will be useful,
+### distorted-keys is distributed in the hope that it will be useful,
 ### but WITHOUT ANY WARRANTY; without even the implied warranty of
 ### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ### GNU General Public License for more details.
 ###
 ### You should have received a copy of the GNU General Public License
-### along with this program; if not, write to the Free Software Foundation,
+### along with distorted-keys; if not, write to the Free Software Foundation,
 ### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 
 quis=${0##*/}
@@ -26,134 +28,739 @@ quis=${0##*/}
 ###--------------------------------------------------------------------------
 ### Configuration variables.
 
+## Automatically configured pathnames.
 PACKAGE="@PACKAGE@" VERSION="@VERSION@"
-pkgconfdir="@pkgconfdir@" pkglibdir="@pkglibdir@"
 bindir="@bindir@"
 
-case ":$PATH:" in *:"$bindir":*) ;; *) PATH=$bindir:$PATH ;; esac
+## Read user configuration.
+if [ -f $ETC/keys.conf ]; then . $ETC/keys.conf; fi
+
+## Maybe turn on debugging.
+case "${KEYS_DEBUG+t}" in t) set -x ;; esac
+
+## Fake up caller credentials if not called via userv.
+case "${USERV_USER+t}" in
+  t) ;;
+  *) USERV_USER=${LOGNAME-${USER-$(id -un)}} USERV_UID=$(id -u) ;;
+esac
+case "${USERV_GROUP+t}" in
+  t) ;;
+  *) USERV_GROUP=$(id -Gn) USERV_GID=$(id -gn) ;;
+esac
 
 ###--------------------------------------------------------------------------
 ### Cleanup handling.
 
 cleanups=""
-cleanup () { cleanups="$cleanups $1"; }
-trap 'rc=$?; for i in $cleanups; do $i; done; exit $rc' EXIT
-trap 'exit 127' INT TERM
+cleanup () { cleanups=${cleanups+$cleanups }$1; }
+runcleanups () { for i in $cleanups; do $i; done; }
+trap 'rc=$?; runcleanups; exit $rc' EXIT
+trap 'trap "" EXIT; runcleanups; exit 127' INT TERM
 
 ###--------------------------------------------------------------------------
 ### Utility functions.
 
+reqsafe () {
+  ## Fail unless a safe directory is set.
+
+  err="$quis: (CONFIGURATION ERROR)"
+  case ${SAFE+t} in
+    t) ;;
+    *) echo >&2 "$err: no SAFE directory"; exit 1 ;;
+  esac
+  if [ ! -d "$SAFE" ]; then
+    echo >&2 "$err: SAFE path \`$SAFE' isn't a directory"
+    exit 1
+  fi
+  case "$SAFE" in
+    [!/]* | *[][[:space:]*?]*)
+      echo >&2 "$err: SAFE path \`$SAFE' contains bad characters"
+      exit 1
+      ;;
+  esac
+  ls -ld "$SAFE" | {
+    me=$(id -un)
+    read perm _ user stuff
+    case "$perm:$user" in
+      d???------:"$me") ;;
+      *)
+       echo >&2 "$err: SAFE path \`$SAFE' has bad owner or permissions"
+       exit 1
+       ;;
+    esac
+  }
+}
+
 ## Temporary directory.
 unset tmp
-rmtmp () { cd /; rm -rf $tmp; }
+rmtmp () { case ${tmp+t} in t) cd /; rm -rf $tmp ;; esac; }
+cleanup rmtmp
 mktmp () {
-  ## Make and return the name of a temporary directory.
+  ## Make a temporary directory and store its name in `tmp'.
 
-  case "${tmp+t}" in t) echo "$tmp"; return ;; esac
-  mem=$(userv root claim-mem-dir)
-  tmp="$mem/keys.tmp.$$"
+  case "${tmp+t}" in t) return ;; esac
+  reqsafe
+  tmp="$SAFE/keys.tmp.$$"
   rm -rf "$tmp"
   mkdir -m700 "$tmp"
-  echo "$tmp"
 }
 
-###--------------------------------------------------------------------------
-### Input validation functions.
+reqtmp () {
+  ## Fail unless a temporary directory is set.
 
-checknumber () {
-  what=$1 thing=$2
-  case "$thing" in
-    "" | [!1-9]* | *[!0-9]*)
-      echo >&2 "$quis: bad $what \`$thing'"
-      exit 1
-      ;;
+  case ${tmp+t} in
+    t) ;;
+    *) echo >&2 "$quis (INTERNAL): no tmp directory set"; exit 127 ;;
+  esac
+}
+
+parse_keylabel () {
+  key=$1
+  ## Parse the key label string KEY.  Set `kdir' to the base path to use for
+  ## the key's storage, and `kowner' to the key owner's name.
+
+  case "$key" in
+    *:*) kowner=${key%%:*} klabel=${key#*:} ;;
+    *) kowner=$USERV_USER klabel=$key ;;
+  esac
+  checkword "key owner name" "$kowner"
+  checklabel "key" "$klabel"
+  kdir=$KEYS/store/$kowner/$klabel
+  knub=$KEYS/nub/$kowner/$klabel
+}
+
+runas () {
+  user=$1 service=$2; shift 2
+  ## If the current (effective) user is not USER then reinvoke via `userv',
+  ## as the specified service, with the remaining arguments.
+
+  case $(id -un) in
+    "$user") ;;
+    *) exec userv "$user" "$service" "$@" ;;
   esac
 }
 
-checkword () {
-  what=$1 thing=$2
+###--------------------------------------------------------------------------
+### Input validation functions.
+
+nl="
+"
+check () {
+  ckwhat=$1 ckpat=$2 thing=$3
+  ## Verify that THING matches the (anchored, basic) regular expression
+  ## CKPAT.  Since matching newlines is hard to do portably, also check that
+  ## THING doesn't contain any.  If the checks fail, report an error and
+  ## exit.
+
+  validp=t
   case "$thing" in
-    "" | *[!-0-9a-zA-Z_!%@+=]*)
-      echo >&2 "$quis: bad $what: \`$thing'"
-      exit 1
-      ;;
+    *"$nl"*) validp=nil ;;
+    *) if ! expr >/dev/null "Q$thing" : "Q$ckpat\$"; then validp=nil; fi ;;
+  esac
+  case $validp in
+    nil) echo >&2 "$quis: bad $ckwhat \`$thing'"; exit 1 ;;
   esac
 }
 
+## Regular expressions for validating input.
+R_IDENTCHARS="A-Za-z0-9_"
+R_GOODPUNCT="!%@+="
+R_WORDCHARS="-$R_IDENTCHARS$R_GOODPUNCT"
+R_IDENT="[$R_IDENTCHARS][$R_IDENTCHARS]*"
+R_WORD="[$R_WORDCHARS][$R_WORDCHARS]*"
+R_ACLCHARS="][$R_IDENTCHARS$R_GOODPUNCT*?:.#"
+R_WORDSEQ="[$R_WORDCHARS[:space:]][$R_WORDCHARS[:space:]]*"
+R_ACL="[$R_ACLCHARS[:space:]-][$R_ACLCHARS[:space:]-]*"
+R_NUMERIC='\(\([1-9][0-9]*\)\{0,1\}0\{0,1\}\)'
+R_LABEL="\($R_WORD\(/$R_WORD\)*\)"
+R_LINE=".*"
+
+## Various validation functions.
+checknumber () { check "$1" "$R_NUMERIC" "$2"; }
+checkident () { check "$1" "$R_IDENT" "$2"; }
+checkword () { check "$1" "$R_WORD" "$2"; }
+checklabel () { check "$1 label" "$R_LABEL" "$2"; }
+
 ###--------------------------------------------------------------------------
-### Crypto operations.
-###
-### We use Seccure for this, but it's interface is Very Annoying.
+### Key storage and properties.
+
+getsysprofile () {
+  profile=$1
+  ## Write the named system PROFILE to standard output.
+
+  $bindir/extract-profile "$profile" $ETC/profile.d/
+}
+
+setprops () {
+  what=$1 prefix=$2; shift 2
+  ## Set variables based on the NAME=VALUE assignments in the arguments.  The
+  ## value for property NAME is stored in the shell variable PREFIX_NAME.
 
-run_seccure () {
-  op=$1; shift
-  ## run_seccure OP ARG ...
+  for assg in "$@"; do
+    goodp=t
+    case "$assg" in
+      *\=*) name=${assg%%=*} value=${assg#*=} ;;
+      *) goodp=nil ;;
+    esac
+    case "$goodp,$name" in t,*[!0-9A-Za-z_]*=*) goodp=nil ;; esac
+    case "$goodp" in
+      nil) echo >&2 "$quis: bad $what assignment \`$assg'"; exit 1 ;;
+    esac
+    eval "$prefix$name=\$value"
+  done
+}
+
+checkprops () {
+  whatprop=$1 prefix=$2; shift 2
+  ## Check that property variables are set in accordance with the remaining
+  ## TABLE arguments.  Each row of TABLE has the form
+  ##
+  ##   NAME OMIT PAT
   ##
-  ## Run a Seccure program, ensuring that its stderr is reported if it had
-  ## anything very interesting to say, but suppressed if it was boring.
+  ## A table row is satisfied if there is a variable PREFIXNAME whose value
+  ## matces the (basic) regular expression PAT, or if the variable is unset
+  ## and OMIT is `t'.
 
-  ## We need a temporary place for the error output.
-  case ${tmp+t} in
-    t) ;;
+  for table in "$@"; do
+    case "$table" in ?*) ;; *) continue ;; esac
+    while read -r name omit pat; do
+      eval foundp=\${$prefix$name+t}
+      case "$foundp,$omit" in
+       ,t) continue ;;
+       ,nil)
+         echo >&2 "$quis: missing $whatprop \`$name' required"
+         exit 1
+         ;;
+      esac
+      eval value=\$$prefix$name
+      check "value for $whatprop \`$name'" "$pat" "$value"
+    done <<EOF
+$table
+EOF
+  done
+}
+
+dumpprops () {
+  prefix=$1
+  ## Write the properties stored in the variables beginning with PREFIX.
+
+  set | sed -n "/^$prefix/{s/=.*\$//;p}" | sort | while read name; do
+    eval value=\$$name
+    echo "${name#$prefix}=$value"
+  done
+}
+
+defprops () {
+  name=$1
+  ## Define a properties table NAME.
+
+  table=$(cat)
+  eval $name=\$table
+}
+
+defprops g_props <<EOF
+type                   nil     $R_IDENT
+recovery               t       $R_WORDSEQ
+random                 t       $R_WORD
+nub_hash               t       $R_WORD
+nubid_hash             t       $R_WORD
+nub_random_bytes       t       $R_NUMERIC
+acl_encrypt            t       $R_ACL
+acl_decrypt            t       $R_ACL
+acl_sign               t       $R_ACL
+acl_verify             t       $R_ACL
+acl_info               t       $R_ACL
+EOF
+
+readprops () {
+  file=$1
+  ## Read a profile from a file.  This doesn't check the form of the
+  ## filename, so it's not suitable for unchecked input.  Properties are set
+  ## using `setprops' with prefix `kprop_'.
+
+  ## Parse the settings from the file.
+  exec 3<"$file"
+  while read line; do
+    case "$line" in "" | \#*) continue ;; esac
+    setprops "property" kprop_ "$line"
+  done <&3
+  exec 3>&-
+  checkprops "property" kprop_ "$g_props"
+
+  ## Fetch the key-type handling library.
+  if [ ! -f $KEYSLIB/ktype.$kprop_type ]; then
+    echo >&2 "$quis: unknown key type \`$kprop_type'"
+    exit 1
+  fi
+  . $KEYSLIB/ktype.$kprop_type
+  checkprops "property" kprop_ "$k_props"
+}
+
+readmeta () {
+  kdir=$1
+  ## Read key metadata from KDIR.
+
+  { read profile; } <"$kdir"/meta
+}
+
+makenub () {
+  ## Generate a key nub in the default way, and write it to standard output.
+  ## The properties `random', `nub_random_bytes' and `nub_hash' are referred
+  ## to.
+
+  dd 2>/dev/null \
+    if=/dev/${kprop_random-random} bs=1 count=${kprop_nub_random_bytes-64} |
+  openssl dgst -${kprop_nub_hash-sha256} -binary |
+  openssl base64
+}
+
+nubid () {
+  ## Compute a hash of the key nub in stdin, and write it to stdout in hex.
+  ## The property `nubid_hash' is used.
+
+  ## Stupid dance because the output incompatibly grew a filename, in order
+  ## to demonstrate the same idiocy as GNU mumblesum.
+  set _ $({ echo "distorted-keys nubid"; cat -; } |
+    openssl dgst -${kprop_nubid_hash-sha256})
+  if [ $# -gt 2 ]; then shift; fi
+  echo $2
+}
+
+subst () {
+  what=$1 templ=$2 prefix=$3 pat=$4
+  ## Substitute option values into the template TEMPL.  Each occurrence of
+  ## %{VAR} is replaced by the value of the variable PREFIXVAR.  Finally, an
+  ## error is reported unless the final value matches the regular expression
+  ## PAT.
+
+  out=""
+  rest=$templ
+  while :; do
+
+    ## If there are no more markers to substitute, then finish.
+    case "$rest" in *"%{"*"}"*) ;; *) out=$out$rest; break ;; esac
+
+    ## Split the template into three parts.
+    left=${rest%%\%\{*} right=${rest#*\%\{}
+    var=${right%%\}*} rest=${right#*\}}
+    case "$var" in
+      *-*) default=${var#*-} var=${var%%-*} defaultp=t ;;
+      *) defaultp=nil ;;
+    esac
+
+    ## Find the variable value.
+    checkident "template variable name" "$var"
+    eval foundp=\${$prefix$var+t}
+    case $foundp,$defaultp in
+      t,*) eval value=\$$prefix$var ;;
+      ,t) value=$default ;;
+      *)
+       echo >&2 "$quis: option \`$var' unset, used in template \`$templ'"
+       exit 1
+       ;;
+    esac
+
+    ## Do the substitution.
+    out=$out$left$value
+  done
+
+  ## Check the final result.
+  check "$what" "$pat" "$out"
+
+  ## Done.
+  echo "$out"
+}
+
+read_profile () {
+  owner=$1 profile=$2
+  ## Read property settings from a profile.  The PROFILE name has the form
+  ## [USER:]LABEL; USER defaults to OWNER.  Properties are set using
+  ## `setprops' with prefix `kprop_'.
+
+  reqtmp
+  case "$profile" in
+    :*)
+      label=${profile#:} uservp=nil
+      ;;
     *)
-      echo >&2 "$quis (INTERNAL): run_seccure called without tmpdir"
-      exit 127
+      user=$kowner label=$profile uservp=t
+      ;;
+    *:*)
+      user=${profile%%:*} label=${profile#*:} uservp=t
       ;;
   esac
+  checkword "profile label" "$label"
 
-  ## Run the program.
-  set +e; seccure-$op "$@" 2>$tmp/seccure.out; rc=$?; set -e
-  grep -v '^WARNING: Cannot obtain memory lock' $tmp/seccure.out >&2 || :
-  return $rc
+  ## Fetch the profile settings from the user.
+  reqtmp
+  case $uservp in
+    t)
+      checkword "profile user" "$user"
+      userv "$user" cryptop-profile "$label" >$tmp/profile </dev/null
+      ;;
+    nil)
+      $bindir/extract-profile "$label" $ETC/profile.d/ >$tmp/profile
+      ;;
+  esac
+
+  ## Read the file.
+  readprops $tmp/profile
+}
+
+###--------------------------------------------------------------------------
+### General crypto operations.
+
+c_genkey () {
+  profile=$1 kdir=$2 knub=$3 hook=$4; shift 4
+  ## Generate a key, and associate it with the named PROFILE (which is
+  ## assumed already to have been read!); store the main data in KDIR, and
+  ## the nub separately in the file KNUB; run HOOK after generation, passing
+  ## it the working key directory and nub file.  Remaining arguments are
+  ## options to the key type.
+
+  ## Set options and check them.
+  setprops "option" kopt_ "$@"
+  checkprops "option" kopt_ "$k_genopts"
+
+  ## Create directory structure and start writing metadata.
+  rm -rf "$kdir.new"
+  mkdir -m755 -p "$kdir.new"
+  case "$knub" in */*) mkdir -m700 -p "${knub%/*}" ;; esac
+  cat >"$kdir.new/meta" <<EOF
+$profile
+EOF
+
+  ## Generate the key.
+  umask=$(umask); umask 077; >"$knub.new"; umask $umask
+  k_generate "$kdir.new" "$knub.new"
+  $hook "$kdir.new" "$knub.new"
+
+  ## Hash the nub.
+  nubid <"$knub.new" >"$kdir.new/nubid"
+
+  ## Juggle everything into place.  Doing this atomically is very difficult,
+  ## and requires more machinery than I can really justify here.  If
+  ## something goes wrong halfway, it should always be possible to fix it,
+  ## either by backing out (if $kdir.new still exists) or pressing on
+  ## forwards (if not).
+  rm -rf "$kdir.old"
+  if [ -e "$kdir" ]; then mv "$kdir" "$kdir.old"; fi
+  mv "$kdir.new" "$kdir"
+  mv "$knub.new" "$knub"
+  rm -rf "$kdir.old"
 }
 
-ec_public () {
-  private=$1
-  ## Write the public key corresponding to PRIVATE to stdout.
+c_encrypt () { k_encrypt "$@"; }
+c_decrypt () {
+  if k_decrypt "$@" >$tmp/plain; then cat $tmp/plain
+  else return $?
+  fi
+}
+c_sign () { k_sign "$@"; }
+c_verify () { k_verify "$@"; }
+
+## Stub implementations.
+notsupp () { op=$1; echo >&2 "$quis: operation \`$op' not supported"; }
+k_info () { :; }
+k_import () { :; }
+k_encrypt () { notsupp encrypt; }
+k_decrypt () { notsupp decrypt; }
+k_sign () { notsupp sign; }
+k_verify () { notsupp verify; }
+
+prepare () {
+  key=$1 op=$2
+  ## Prepare for a crypto operation OP, using the KEY.  This validates the
+  ## key label, reads the profile, and checks the access-control list.  If OP
+  ## is `-' then allow the operation unconditionally.
 
-  run_seccure key -q -cp256 -F"$private"
+  ## Find the key properties.
+  parse_keylabel "$key"
+  if [ ! -d $kdir ]; then echo >&2 "$quis: unknown key \`$key'"; exit 1; fi
+  readmeta $kdir
+  read_profile $kowner "$profile"
+
+  ## Check whether we're allowed to do this thing.  This is annoyingly
+  ## fiddly.
+  case $op in -) return ;; esac
+  eval acl=\${kprop_acl_$op-!owner}
+  verdict=forbid
+  while :; do
+
+    ## Remove leading whitespace.
+    while :; do
+      case "$acl" in
+       [[:space:]]*) acl=${acl#?} ;;
+       *) break ;;
+      esac
+    done
+
+    ## If there's nothing left, leave.
+    case "$acl" in ?*) ;; *) break ;; esac
+
+    ## Split off the leading word.
+    case "$acl" in
+      *[[:space:]]*) word=${acl%%[[:space:]]*} acl=${acl#*[[:space:]]} ;;
+      *) word=$acl acl="" ;;
+    esac
+
+    ## See what sense it has if it matches.
+    case "$word" in
+      -*) sense=forbid rest=${word#-} ;;
+      *) sense=allow rest=$word ;;
+    esac
+
+    ## See whether the calling user matches.
+    case "$rest" in
+      !owner) pat=$kowner list=$USERV_USER ;;
+      !*) echo >&2 "$quis: unknown ACL token \`$word'" ;;
+      %*) pat=${rest#%} list="$USERV_GROUP $USERV_GID" ;;
+      *) pat=$rest list="$USERV_USER $USERV_UID" ;;
+    esac
+    matchp=nil
+    for i in $list; do case "$i" in $pat) matchp=t; break ;; esac; done
+    case $matchp in t) verdict=$sense; break ;; esac
+  done
+
+  case $verdict in
+    forbid) echo >&2 "$quis: $op access to key \`$key' forbidden"; exit 1 ;;
+  esac
 }
 
-ec_keygen () {
-  private=$1 public=$2
-  ## Make a new key, write private key to PRIVATE and public key to PUBLIC.
+###--------------------------------------------------------------------------
+### Crypto operations for infrastructure purposes.
+
+c_sysprofile () {
+  profile=$1
+  ## Select the profile in FILE for future crypto operations.
 
-  dd if=/dev/random bs=1 count=512 2>/dev/null |
-    openssl sha384 -binary |
-    (umask 077 && openssl base64 >"$private")
-  ec_public "$private" >"$public"
+  unset $(set | sed -n '/^kprop_/s/=.*$//p')
+  reqtmp
+  getsysprofile "$profile" >$tmp/profile
+  readprops $tmp/profile
 }
 
-ec_encrypt () {
-  public=$1; shift
-  ## Encrypt stuff using the PUBLIC key.  Use -i/-o or redirection.
+c_gensyskey () {
+  profile=$1 kdir=$2 knub=$3; shift 3
+  ## Generate a system key using PROFILE; store the data in KDIR and the nub
+  ## in KNUB.  Remaining arguments are options.
 
-  run_seccure encrypt -q -cp256 -m128 "$@" -- $(cat "$public")
+  c_sysprofile "$profile"
+  c_genkey "$profile" "$kdir" "$knub" : "$@"
 }
 
-ec_decrypt () {
-  private=$1; shift
-  ## Decrypt stuff using the PRIVATE key.  Use -i/-o or redirection.
+c_sysprepare () {
+  kdir=$1
+  readmeta "$kdir"
+  c_sysprofile "$profile"
+}
 
-  run_seccure decrypt -q -cp256 -m128 -F"$private" "$@"
+c_sysop () {
+  op=$1 kdir=$2; shift 1
+  c_sysprepare "$kdir"
+  c_$op "$@"
+}
+
+c_sysencrypt () { c_sysop encrypt "$1" /dev/null; }
+c_sysdecrypt () { c_sysop decrypt "$1" "$2"; }
+c_syssign () { c_sysop sign "$1" "$2"; }
+c_sysverify () { c_sysop verify "$1" /dev/null; }
+
+###--------------------------------------------------------------------------
+### Recovery operations.
+
+sharethresh () {
+  pf=$1
+  ## Return the sharing threshold from the parameter file PARAM.
+
+  read param <"$pf"
+  case "$param" in
+    shamir-params:*) ;;
+    *)
+      echo >&2 "$quis: secret sharing parameter file damaged (wrong header)"
+      exit 1
+      ;;
+  esac
+  t=";${param#*:}"
+  case "$t" in
+    *";t="*) ;;
+    *)
+      echo >&2 "$quis: secret sharing parameter file damaged (missing t)"
+      exit 1
+      ;;
+  esac
+  t=${t#*;t=}
+  t=${t%%;*}
+  echo "$t"
+}
+
+stash () {
+  recov=$1 label=$2
+  ## Stash a copy of stdin encrypted under the recovery key RECOV, with a
+  ## given LABEL.
+  checkword "recovery key label" "$recov"
+  checklabel "secret" "$label"
+
+  rdir=$KEYS/recov/$recov/current
+  if [ ! -d $rdir/store ]; then
+    echo >&2 "$quis: unknown recovery key \`$recov'"
+    exit 1
+  fi
+  case $label in */*) mkdir -m755 -p $rdir/${label%/*} ;; esac
+  (c_sysencrypt $rdir/store >$rdir/$label.new)
+  mv $rdir/$label.new $rdir/$label.recov
+}
+
+recover () {
+  recov=$1 inst=$2 label=$3
+  ## Recover a stashed secret, protected by RECOV and stored as LABEL, and
+  ## write it to stdout.
+  checkword "recovery key label" "$recov"
+  checkword "recovery instance" "$inst"
+  checklabel "secret" "$label"
+
+  rdir=$KEYS/recov/$recov/$inst
+  if [ ! -f $rdir/$label.recov ]; then
+    echo >&2 "$quis: recovery key \`$recov/$inst' has no blob for \`$label'"
+    exit 1
+  fi
+  reqsafe
+  tag=$recov.$inst
+  nub=$SAFE/keys.reveal/$tag/nub
+  if [ ! -f $nub ]; then
+    echo >&2 "$quis: recovery key \`$recov/$inst' not revealed"
+    exit 1;
+  fi
+  mktmp
+  c_sysdecrypt $rdir/store $nub <$rdir/$label.recov
 }
 
 ###--------------------------------------------------------------------------
 ### Help text.
 
-dohelp () {
-  case "$KEYS_HELP" in t) ;; *) return ;; esac
-  help; exit
+defhelp () {
+  read umsg
+  usage=$umsg
+  help=$(cat)
+  case "$KEYS_HELP" in t) help; exit ;; esac
 }
 
-defhelp () { read umsg; usage="usage: $quis${umsg+ }$umsg"; help=$(cat); }
 help () { showhelp; }
 showhelp () {
   cat <<EOF
-$usage
+Usage: $quis${usage:+ $usage}
 
 $help
 EOF
 }
 
+usage () {
+  : ${cmdargs=$usage}
+  echo "usage: $quis${cmdname:+ $cmdname}${cmdargs:+ $cmdargs}"
+}
+usage_err () { usage >&2; exit 1; }
+
+###--------------------------------------------------------------------------
+### Subcommand handling.
+
+version () {
+  echo "$PACKAGE version $VERSION"
+}
+
+unset cmdargs
+unset cmdname
+cmds=""
+defcmd () {
+  cmd=$1; shift; args=$*
+  help=$(cat)
+  eval help_$cmd=\$help
+  cmds="${cmds:+$cmds
+}$cmd $args"
+}
+
+defcmd help "[COMMAND ...]" <<EOF
+Show help about the COMMANDs, or about $quis if none are named.
+EOF
+cmd_help () {
+  rc=0
+  version
+  case $# in
+    0)
+      cat <<EOF
+
+Usage: $quis${usage:+ $usage}
+
+Options:
+  -h           Show this help text.
+  -v           Show the program version number.
+
+Commands provided:
+EOF
+      while read cmd args; do echo "   $cmd${args:+ $args}"; done <<EOF
+$cmds
+EOF
+      case ${prefix+t} in
+       t)
+         cd $KEYSLIB
+         for i in $prefix.*; do
+           if [ ! -x "$i" ]; then continue; fi
+           sed -n "/<<HELP/{n;s/^/     ${i#$prefix.} /;p;q;}" "$i"
+         done
+         ;;
+      esac
+      ;;
+    *)
+      for cmd in "$@"; do
+       echo
+       foundp=nil
+       while read cmdname cmdargs; do
+         case $cmdname in "$cmd") foundp=t; break ;; esac
+       done <<EOF
+$cmds
+EOF
+       case $foundp in
+         t)
+           eval help=\$help_$cmdname; echo "$help"
+           ;;
+         nil)
+           if [ ! -x "$KEYSLIB/$prefix.$cmd" ]; then
+             echo >&2 "$quis: unrecognized command \`$cmd'"
+             rc=1
+             continue
+           elif ! KEYS_HELP=t "$KEYSLIB/$prefix.$cmd"; then
+             rc=1
+           fi
+           ;;
+       esac
+      done
+      ;;
+  esac
+  return $rc
+}
+
+dispatch () {
+  case $# in 0) usage_err ;; esac
+  cmd=$1; shift
+  foundp=nil
+  while read cmdname cmdargs; do
+    case $cmdname in "$cmd") foundp=t; break ;; esac
+  done <<EOF
+$cmds
+EOF
+  case $foundp in
+    t)
+      OPTIND=1
+      cmd_$cmdname "$@"
+      ;;
+    nil)
+      if [ ! -x "$KEYSLIB/$prefix.$cmd" ]; then
+       echo >&2 "$quis: unrecognized command \`$cmd'"
+       exit 1
+      fi
+      unset KEYS_HELP
+      exec "$KEYSLIB/$prefix.$cmd" "$@"
+      ;;
+  esac
+}
+
 ###----- That's all, folks --------------------------------------------------