glenda.party
term% ls -F
term% pwd
$home/manuals/9front/3/cap
term% cat index.txt
CAP(3)                     Library Functions Manual                     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 an‐
       other process may then use to change its user id.  The intent is to al‐
       low  server  processes,  for example telnetd (see ipserv(8)), to change
       their user id after having proved to a trusted process, such as  facto‐
       tum(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 concatena‐
       tion of an old user name, an ``@'', a new user name, an  ``@'',  and  a
       string  of  randomly  generated characters 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  corre‐
       sponding  capability  is  used  or  after a minute has passed since the
       write to caphash.

       The trusted process may then pass the capability to any process 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 computes the same hash using the supplied capabil‐
       ity 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 capability.

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

SEE ALSO
       sechash(2)

DIAGNOSTICS
       Errors  generated  by reading and writing caphash and capuse can be ob‐
       tained 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''.



                                                                        CAP(3)