82 lines
2.1 KiB
Plaintext
82 lines
2.1 KiB
Plaintext
|
.TH CAP 3
|
||
|
|
.SH NAME
|
||
|
|
cap \- capabilities for setting the user id of processes
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.B bind #¤
|
||
|
|
.I dir
|
||
|
|
.nf
|
||
|
|
|
||
|
|
.IB dir /caphash
|
||
|
|
.IB dir /capuse
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
.B telnetd
|
||
|
|
(see
|
||
|
|
.IR ipserv (8)),
|
||
|
|
to change their user id after having proved
|
||
|
|
to a trusted process, such as
|
||
|
|
.IR 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
|
||
|
|
.B /dev/hostowner
|
||
|
|
in
|
||
|
|
.IR cons (3)).
|
||
|
|
.PP
|
||
|
|
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 characters called the key.
|
||
|
|
The trusted process enables the kernel to authenticate
|
||
|
|
capabilities passed to it by writing to
|
||
|
|
.I caphash
|
||
|
|
a secure hash of the capability.
|
||
|
|
The hash is 20 bytes long and generated by the following call:
|
||
|
|
.EX
|
||
|
|
|
||
|
|
hmac_sha1(old_at_new, strlen(old_at_new), key, strlen(key),
|
||
|
|
hash, nil);
|
||
|
|
|
||
|
|
.EE
|
||
|
|
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
|
||
|
|
.IR caphash .
|
||
|
|
.PP
|
||
|
|
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
|
||
|
|
.IR capuse .
|
||
|
|
The kernel computes 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 capability.
|
||
|
|
.SH SOURCE
|
||
|
|
.B /sys/src/9/port/devcap.c
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
.IR sechash (2)
|
||
|
|
.SH DIAGNOSTICS
|
||
|
|
.PP
|
||
|
|
Errors generated by reading and writing
|
||
|
|
.I caphash
|
||
|
|
and
|
||
|
|
.I capuse
|
||
|
|
can be obtained using
|
||
|
|
.IR errstr (2).
|
||
|
|
A read of
|
||
|
|
.I caphash
|
||
|
|
with a length of less than 20
|
||
|
|
or a write to
|
||
|
|
.I capuse
|
||
|
|
that doesn't contain two @ characters
|
||
|
|
generates the error ``read or write too small''.
|
||
|
|
A write to
|
||
|
|
.I capuse
|
||
|
|
that has no matching hash generates the error
|
||
|
|
``invalid capability''.
|