1
0

cap 2.1 KB

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