ref: d916a4c3823f55227ffae35738c2497256e307b5
dir: /man/3/cap/
.TH CAP 3
.SH NAME
cap \- capability for changing user name
.SH SYNOPSIS
.BI "bind #¤ " dir
.PP
.IB dir /caphash
.br
.IB dir /capuse
.SH DESCRIPTION
.I Cap
allows a process owned by the host owner (see
.IR eve (10.2))
to give another process on the same machine
a capability to set its user name to a specified user.
The capability is a string of the form:
.IP
[
.IB fromuser @
]
.IB touser @ key
.PP
where
.I fromuser
is a process's current user name,
.I touser
is its new user name, and
.I key
is a string of random characters
(eg, produced by
.IR security-random (2)).
.PP
.B Caphash
is a write-only file that can only be opened by the host owner.
A process enables the use of a capability by writing the keyed hash of
.IB fromuser @ touser
to
.BR caphash .
The hash is computed using
.B Keyring->hmac_sha1
as follows:
.IP
.EX
kr := load Keyring Keyring->PATH;
IPint: import kr;
users := sys->sprint("%s@%s", fromuser, touser);
cap := sys->sprint("%s@%s", users, key);
digest := array[Keyring->SHA1dlen] of byte;
ausers := array of byte users;
kr->hmac_sha1(ausers, len ausers, array of byte key, digest, nil);
if(sys->write(caphashfd, digest, len digest) < 0)
error();
.EE
.PP
The capability (eg,
.B cap
in the example)
can then be passed to another process.
.PP
.B Capuse
is a write-only file that can be opened by any process.
It can then write a capability string to change its user name,
provided that capability has previously been enabled by the host owner via
.BR caphash ,
and if the capability included a
.IR fromuser ,
the writing process currently has that user name.
After a successful write, the writing process will be owned by
.IR touser .
Any capability can be used at most once.
.PP
A capability enabled by
.B caphash
has a limited lifetime, on the order of 30 seconds.
.B Caphash
can be removed by the host owner to prevent its further use.
.SH SOURCE
.B /emu/port/devcap.c
.br
.B /os/port/devcap.c
.SH SEE ALSO
.IR keyring-sha1 (2),
.IR cons (3),
.IR intro (5),
.IR eve (10.2)
.SH DIAGNOSTICS
A write to
.B capuse
without a previous write to
.B caphash
sets the error string to
.RB `` "invalid capability" ''.