keyfunc.sh.in: Add come commentary to the configuration section.

[distorted-keys] / keyfunc.sh.in

### -*-sh-*-
###
### Common key management functions.
###
### (c) 2011 Mark Wooding
###

###----- Licensing notice ---------------------------------------------------
###
### 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.
###
### 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 distorted-keys; if not, write to the Free Software Foundation,
### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

quis=${0##*/}

###--------------------------------------------------------------------------
### Configuration variables.

## Automatically configured pathnames.
PACKAGE="@PACKAGE@" VERSION="@VERSION@"
bindir="@bindir@"

## 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

###--------------------------------------------------------------------------
### Cleanup handling.

cleanups=""
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 () { case ${tmp+t} in t) cd /; rm -rf $tmp ;; esac; }
cleanup rmtmp
mktmp () {
  ## Make a temporary directory and store its name in `tmp'.

  case "${tmp+t}" in t) return ;; esac
  reqsafe
  tmp="$SAFE/keys.tmp.$$"
  rm -rf "$tmp"
  mkdir -m700 "$tmp"
}

reqtmp () {
  ## Fail unless a temporary directory is set.

  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
}

###--------------------------------------------------------------------------
### 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
    *"$nl"*) validp=nil ;;
    *) if ! expr >/dev/null "$thing" : "$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_WORDCHARS="-$R_IDENTCHARS!%@+="
R_IDENT="[$R_IDENTCHARS][$R_IDENTCHARS]*"
R_WORD="[$R_WORDCHARS][$R_WORDCHARS]*"
R_WORDSEQ="[$R_WORDCHARS[:space:]][$R_WORDCHARS[: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"; }

###--------------------------------------------------------------------------
### 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.

  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
  ##
  ## 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'.

  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
}

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
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.

  { echo "distorted-keys nubid"; cat -; } |
  openssl dgst -${kprop_nubid_hash-sha256}
}

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 () {
  profile=$1
  ## Read property settings from a profile.  The PROFILE name has the form
  ## [USER:]LABEL.  Properties are set using `setprops' with prefix `kprop_'.

  reqtmp
  case "$profile" in
    :*)
      label=${profile#:} uservp=nil
      ;;
    *)
      user=$USERV_USER label=$profile uservp=t
      ;;
    *:*)
      user=${profile%%:*} label=${profile#*:} uservp=t
      ;;
  esac
  checkword "profile label" "$label"

  ## Fetch the profile settings from the user.
  reqtmp
  case $uservp in
    t)
      checkword "profile user" "$user"
      userv "$user" cryptop-profile "$label" >$tmp/profile
      ;;
    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"
}

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_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.

  ## Find the key properties.
  parse_keylabel "$key"
  if [ ! -d $kdir ]; then echo >&2 "$quis: unknown key \`$key'"; exit 1; fi
  readmeta $kdir
  read_profile "$profile"

  ## Check whether we're allowed to do this thing.  This is annoyingly
  ## fiddly.
  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
}

###--------------------------------------------------------------------------
### Crypto operations for infrastructure purposes.

c_sysprofile () {
  profile=$1
  ## Select the profile in FILE for future crypto operations.

  unset $(set | sed -n '/^kprop_/s/=.*$//p')
  reqtmp
  getsysprofile "$profile" >$tmp/profile
  readprops $tmp/profile
}

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.

  c_sysprofile "$profile"
  c_genkey "$profile" "$kdir" "$knub" : "$@"
}

c_sysprepare () {
  kdir=$1
  readmeta "$kdir"
  c_sysprofile "$profile"
}

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.

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 label=$2
  ## Recover a stashed secret, protected by RECOV and stored as LABEL, and
  ## write it to stdout.
  checkword "recovery key label" "$recov"
  checklabel "secret" "$label"

  rdir=$KEYS/recov/$recov/current
  if [ ! -f $rdir/$label.recov ]; then
    echo >&2 "$quis: no blob for \`$label' under recovery key \`$recov'"
    exit 1
  fi
  reqsafe
  nub=$SAFE/keys.reveal/$recov.current/nub
  if [ ! -f $nub ]; then
    echo >&2 "$quis: current recovery key \`$recov' not revealed"
    exit 1;
  fi
  mktmp
  c_sysdecrypt $rdir/store $nub <$rdir/$label.recov
}

###--------------------------------------------------------------------------
### Help text.

defhelp () {
  read umsg
  usage="usage: $quis${umsg+ }$umsg"
  help=$(cat)
  case "$KEYS_HELP" in t) help; exit ;; esac
}

help () { showhelp; }
showhelp () {
  cat <<EOF
$usage

$help
EOF
}

usage_err () { echo >&2 "$usage"; exit 1; }

###--------------------------------------------------------------------------
### Subcommand handling.

version () {
  echo "$PACKAGE version $VERSION"
}

cmd_help () {
  rc=0
  version
  case $# in
    0)
      cat <<EOF

$usage

Options:
  -h		Show this help text.
  -v		Show the program version number.

Commands installed:
EOF
      cd "$KEYSLIB"
      for i in $prefix.*; do
	if [ ! -x "$i" ]; then continue; fi
	sed -n "/<<HELP/{n;s/^/	${i#$prefix.} /;p;q;}" "$i"
      done
      ;;
    *)
      for i in "$@"; do
	echo
	if [ ! -x "$KEYSLIB/$prefix.$i" ]; then
	  echo >&2 "$quis: unrecognized command \`$i'"
	  rc=1
	  continue
	elif ! KEYS_HELP=t "$KEYSLIB/$prefix.$i"; then
	  rc=1
	fi
      done
      ;;
  esac
  return $rc
}

dispatch () {
  case $# in 0) echo >&2 "$usage"; exit 1 ;; esac
  cmd=$1; shift
  case "$cmd" in help) cmd_help "$@"; exit ;; esac
  if [ ! -x "$KEYSLIB/$prefix.$cmd" ]; then
    echo >&2 "$quis: unrecognized command \`$cmd'"
    exit 1
  fi

  unset KEYS_HELP
  exec "$KEYSLIB/$prefix.$cmd" "$@"
}

###----- That's all, folks --------------------------------------------------