CAP(3)                                                     CAP(3)

     NAME
          cap - capabilities for setting the user id of processes

     SYNOPSIS
          bind #ยค dir

          dir/caphash
          dir/capuse

     DESCRIPTION
          This device enables a trusted process to create a capability
          that another process may then use to change its user id.
          The intent is to allow server processes, for example telnetd
          (see ipserv(8)), to change their user id after having proved
          to a trusted process, such as factotum(4), that they are
          indeed executing on behalf of a user.  A trusted process is
          one running with the user id of the host owner (see
          /dev/hostowner in cons(3)).

          A capability is a null terminated string consisting of the
          concatenation of an old user name, an ``@'', a new user
          name, an ``@'', and a string of randomly generated charac-
          ters called the key.  The trusted process enables the kernel
          to authenticate capabilities passed to it by writing to
          caphash a secure hash of the capability.  The hash is 20
          bytes long and generated by the following call:

               hmac_sha1(old_at_new, strlen(old_at_new), key, strlen(key),
                    hash, nil);

          The kernel maintains a list of hashes, freeing them after
          the corresponding capability is used or after a minute has
          passed since the write to caphash.

          The trusted process may then pass the capability to any pro-
          cess running as the old user.  That process may then use the
          capability to change identity to the new user.  A process
          uses a capability by writing it to capuse. The kernel com-
          putes the same hash using the supplied capability and
          searches its list of hashes for a match.  If one is found,
          the kernel sets the process's user id to that in the capa-
          bility.

     SOURCE
          /sys/src/9/port/devcap.c

     SEE ALSO
          sechash(2)

     DIAGNOSTICS

     Page 1                       Plan 9             (printed 3/28/24)

     CAP(3)                                                     CAP(3)

          Errors generated by reading and writing caphash and capuse
          can be obtained using errstr(2). A read of caphash with a
          length of less than 20 or a write to capuse that doesn't
          contain two @ characters generates the error ``read or write
          too small''.  A write to capuse that has no matching hash
          generates the error ``invalid capability''.

     Page 2                       Plan 9             (printed 3/28/24)