sys/man/3/cap

   1 .TH CAP 3
   2 .SH NAME
   3 cap \- capabilities for setting the user id of processes
   4 .SH SYNOPSIS
   5 .B bind #¤
   6 .I dir
   7 .nf
   8
   9 .IB dir /caphash
  10 .IB dir /capuse
  11 .fi
  12 .SH DESCRIPTION
  13 .PP
  14 This device enables a trusted process to
  15 create a capability that another process
  16 may then use to change its user id.  The intent is to allow
  17 server processes, for example
  18 .B telnetd
  19 (see
  20 .IR ipserv (8)),
  21 to change their user id after having proved
  22 to a trusted process, such as
  23 .IR factotum (4),
  24 that they are indeed executing
  25 on behalf of a user.
  26 A trusted process is one running with the user id
  27 of the host owner (see
  28 .B /dev/hostowner
  29 in
  30 .IR cons (3)).
  31 .PP
  32 A capability is a null terminated string consisting of the concatenation of
  33 an old user name, an ``@'', a new user name, an ``@'', and a string of randomly
  34 generated characters called the key.
  35 The trusted process enables the kernel to authenticate
  36 capabilities passed to it by writing to
  37 .I caphash
  38 a secure hash of the capability.
  39 The hash is 20 bytes long and generated by the following call:
  40 .EX
  41
  42         hmac_sha1(old_at_new, strlen(old_at_new), key, strlen(key),
  43                 hash, nil);
  44
  45 .EE
  46 The kernel maintains a list of hashes, freeing them after the
  47 corresponding capability is used or after a minute has passed
  48 since the write to
  49 .IR caphash .
  50 .PP
  51 The trusted process may then pass the capability to any process
  52 running as the old user.  That process may then
  53 use the capability to change identity to the new user.
  54 A process uses a capability by writing it to
  55 .IR capuse .
  56 The kernel computes the same hash using the supplied capability
  57 and searches its list of hashes for a match.  If one is found,
  58 the kernel sets the process's user id to that in the capability.
  59 .SH SOURCE
  60 .B /sys/src/9/port/devcap.c
  61 .SH "SEE ALSO"
  62 .IR sechash (2)
  63 .SH DIAGNOSTICS
  64 .PP
  65 Errors generated by reading and writing
  66 .I caphash
  67 and
  68 .I capuse
  69 can be obtained using
  70 .IR errstr (2).
  71 A read of
  72 .I caphash
  73 with a length of less than 20
  74 or a write to
  75 .I capuse
  76 that doesn't contain two @ characters
  77 generates the error ``read or write too small''.
  78 A write to
  79 .I capuse
  80 that has no matching hash generates the error
  81 ``invalid capability''.