Subversion Repositories planix.SVN

.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''.