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)