NAME
     factotum - the deck's key, as three files

SYNOPSIS
     /dev/factotum/ctl
     /dev/factotum/key
     /dev/factotum/sign

DESCRIPTION
     Factotum holds this deck's private key and is the only thing that ever
     touches it.  Everything else -- the shell, a board, a crystal, the mesh --
     asks factotum to sign, and is handed a signature.  The key itself has no
     path.

     It is named for Plan 9's agent of the same job, and it is the same idea:
     authentication is a file server, so the things that need it need no
     library, no linkage and no special call.  Writing a line to a file is the
     whole interface.

     For what a person types rather than what a program writes, see id(1); it
     is a script over these three files and nothing more.

   /dev/factotum/ctl
     Read it for the deck's standing:

          key loaded
          user ada
          addr cb:14:15:b2:02:32

     or, on a deck that has never minted one:

          no key
          user (none)

     Write one of these to it.

     genkey
          Generate a keypair and persist it.  This replaces an existing key
          without asking -- the guard against that lives in id(1), not here.

     delkey
          Forget the keypair, in memory and in storage.

     user name
          Set the name kept alongside the key.  It is persisted, exported to
          the shell as $user, and offered as the deck's mesh beacon name if it
          is beacon-safe.  It is a local name: claiming one on a board is
          handle(1).

     status
          Accepted and does nothing.  Read the file instead.

   /dev/factotum/key
     The public half, in the single line a crystal wants for provisioning: the
     address as twelve hex digits, a vertical bar, then the
     SubjectPublicKeyInfo in base64.

          cb1415b20232|MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE4Atl...

     The file is absent until a key exists: it is not in the directory, and
     opening it fails with "no such file" rather than returning nothing.  That
     is what makes

          test -e /dev/factotum/key

     the way to ask whether this deck has an identity, and it is what
     attune(1) notices when it offers to mint one.

   /dev/factotum/sign
     Write a message, read its signature.

          echo 'hello world' >/dev/factotum/sign
          sig=`{cat /dev/factotum/sign}

     The write hashes the message with SHA-256 and signs the hash; the read
     returns the signature as hex and a newline.  Messages longer than 256
     bytes are truncated to 256, not refused.  Writing without a key fails.

     A signature is read once.  The second read of the same signature returns
     nothing, which is deliberate: a signature left sitting in a file is a
     signature somebody else can pick up.

THE ADDRESS
     The address is the first six bytes of the SHA-256 of the public key.
     That is the whole of it; nothing assigns it and nothing records it
     anywhere.

     Verifying somebody is therefore two steps and no lookup: hash the public
     key they present and check it gives the address they claim, then check
     the signature against that key.  There is no authority in the loop, so
     the check works between two decks in a field with no network, which is
     the point.

     See id(1) for what this means to a person and aether(3) for the layer
     that carries it.

SECURITY
     The private key is never readable through these files, and it is never
     stored in the clear.  On the way to flash it is encrypted with
     AES-256-GCM under a key derived by HKDF-SHA256 from the chip's own eFuse-
     burned identifier, with a fixed salt for domain separation.

     The consequence worth knowing is that the encryption key is derived from
     the hardware and stored nowhere.  The deck's identity cannot be copied
     off it, cannot be moved to another deck, and does not survive its flash
     being erased.  Nothing about this can be worked around; it is what the
     identity is worth.

IMPLEMENTATION
     All of it through the PSA Crypto API: P-256 keys and ECDSA-SHA256
     signing, HKDF-SHA256 derivation, AES-256-GCM, SHA-256.  The unique
     identifier comes from Zephyr's hwinfo driver.

FILES
     src/dev_factotum.c
          The server.

     src/cga.c
          The cryptography under it.

SEE ALSO
     id(1), handle(1), attune(1), aether(3)

     Plan 9's factotum(4), which is a larger thing: it holds many keys for
     many protocols, and this holds one key for one.

     RFC 3972, for cryptographically generated addresses in general.

BUGS
     Signing is one message at a time for the whole deck: a second writer
     overwrites the first writer's pending signature.  Nothing in the deck
     signs often enough for this to have bitten, but two things doing it at
     once would interleave.

FRST Computer                                                      FACTOTUM(3)
