Import sources from 2011-03-30 iso image - sys/man

1 files changed, 81 insertions, 0 deletions

diff --git a/sys/man/3/cap b/sys/man/3/cap
new file mode 100755
index 000000000..1f526fa3e
--- /dev/null
+++ b/sys/man/3/cap
@@ -0,0 +1,81 @@
+.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''.