keyfs 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249
  1. .TH KEYFS 4
  2. .SH NAME
  3. keyfs, warning \- authentication database files
  4. .SH SYNOPSIS
  5. .B auth/keyfs
  6. [
  7. .B -p
  8. ]
  9. [
  10. .B -w
  11. .RB [ np ]
  12. ]
  13. [
  14. .BI -m mntpt
  15. ]
  16. [
  17. .I keyfile
  18. ]
  19. .PP
  20. .B auth/warning
  21. [
  22. .B -n
  23. ]
  24. [
  25. .B -p
  26. ]
  27. .SH DESCRIPTION
  28. .I Keyfs
  29. serves a two-level file tree for manipulating authentication information.
  30. It runs on the machine providing authentication service for the local
  31. Plan 9 network, which may be a dedicated authentication server or
  32. a CPU server.
  33. The programs described in
  34. .IR auth (8)
  35. use
  36. .I keyfs
  37. as their interface to the authentication database.
  38. .PP
  39. .I Keyfs
  40. reads and decrypts file
  41. .I keyfile
  42. (default
  43. .BR /adm/keys )
  44. using the DES key,
  45. which is by default read from
  46. .B #r/nvram
  47. (see
  48. .IR rtc (3)).
  49. With option
  50. .BR -p ,
  51. .I keyfs
  52. prompts for a password from which the key is derived.
  53. .I Keyfile
  54. holds a 41-byte record for each user in the database.
  55. Each record is encrypted separately
  56. and contains the user's name,
  57. DES key,
  58. status,
  59. host status,
  60. and expiration date.
  61. The name is a
  62. null-terminated
  63. .SM UTF
  64. string
  65. .B NAMELEN
  66. bytes long.
  67. The status is a byte containing
  68. binary 0 if the account is enabled,
  69. 1 if it is disabled.
  70. Host status is a byte containing
  71. binary 1 if the user is a host,
  72. 0 otherwise.
  73. The expiration date is four-byte little-endian integer
  74. which represents the time in seconds since the epoch
  75. (see
  76. .IR date (1))
  77. at which the account will expire.
  78. If any changes are made to the database that affect the information stored in
  79. .IR keyfile ,
  80. a new version of the file is written.
  81. .PP
  82. There are two authentication databases,
  83. one for Plan 9 user information,
  84. and one for SecureNet user information.
  85. A user need not be installed in both databases
  86. but must be installed in the Plan 9 database to connect to a Plan 9 server.
  87. .PP
  88. .I Keyfs
  89. serves an interpretation of the
  90. .I keyfile
  91. in the file tree rooted at
  92. .I mntpt
  93. (default
  94. .BR /mnt/keys ).
  95. Each user
  96. .I user
  97. in
  98. .I keyfile
  99. is represented as the directory
  100. .IR mntpt / user .
  101. .PP
  102. Making a new directory in
  103. .I mntpt
  104. creates a new user entry in the database.
  105. Removing a directory removes the user entry,
  106. and renaming it changes the name in the entry.
  107. Such changes are reflected immediately in
  108. .IR keyfile .
  109. .I Keyfs
  110. does not allow duplicate names when creating or renaming user entries.
  111. .PP
  112. All files in the user directories except for
  113. .B key
  114. contain
  115. .SM UTF
  116. strings with a trailing newline when read,
  117. and should be written as
  118. .SM UTF
  119. strings with or without a trailing newline.
  120. .B Key
  121. contains the
  122. .BR DESKEYLEN -byte
  123. encryption key for the user.
  124. .PP
  125. The following files appear in the user directories.
  126. .TF expire
  127. .TP
  128. .B key
  129. The authentication key for the user.
  130. If the user's account is disabled or expired,
  131. reading this file returns an error.
  132. Writing
  133. .I key
  134. changes the key in the database.
  135. .TP
  136. .B log
  137. The number of consecutive failed authentication attempts for the user.
  138. Writing the string
  139. .B bad
  140. increments this number; writing
  141. .B good
  142. resets it to 0.
  143. This number is not stored in
  144. .IR keyfile ,
  145. and is initialized to 0 when
  146. .I keyfs
  147. starts.
  148. When the number reaches a multiple of ten,
  149. .I keyfs
  150. temporarily disables the account for that many seconds.
  151. Reads from the
  152. .B key
  153. or
  154. .B secret
  155. files during this time return the error
  156. ``user in purgatory.''
  157. .TP
  158. .B status
  159. The current status of the account, either
  160. .B ok
  161. or
  162. .BR disabled .
  163. Writing
  164. .B ok
  165. enables the account;
  166. writing
  167. .B disabled
  168. disables it.
  169. .TP
  170. .B expire
  171. The expiration time for the account.
  172. When read, it contains either the string
  173. .B never
  174. or the time in seconds since the epoch
  175. that the account will expire.
  176. When written with strings of the same form,
  177. it sets the expiration date for the user.
  178. If the expiration date is reached,
  179. the account is not disabled,
  180. but
  181. .I key
  182. cannot be read without an error.
  183. .PD
  184. .PP
  185. If the
  186. .B -w
  187. option is on,
  188. .I keyfs
  189. runs the command
  190. .I warning
  191. once every 24 hours to mail people about expiring keys.
  192. Warnings are sent 14 days and 7 days prior to expiration.
  193. The argument to
  194. .BR -w ,
  195. either
  196. .B p
  197. or
  198. .BR n ,
  199. is passed to
  200. .I warning
  201. to restrict the warnings to
  202. the Plan 9 or SecureNet database.
  203. The default for
  204. .I keyfs
  205. is not to call
  206. .I warning
  207. at all;
  208. .I warning's
  209. own default is to warn about both.
  210. The files
  211. .B /adm/netkeys.who
  212. and
  213. .B /adm/keys.who
  214. are used to find the mail addresses to send to.
  215. The first word on each line identifies
  216. a user.
  217. Any subsequent strings on the line delimited '<' and '>' are considered mail
  218. addresses to send warnings to.
  219. If multiple lines match a user, the last in the file is used.
  220. .B Changeuser
  221. (see
  222. .IR auth (8))
  223. adds lines to these files.
  224. .SH FILES
  225. .TF /adm/netkeys.who
  226. .TP
  227. .B /adm/keys
  228. Encrypted key file for the Plan 9 database.
  229. .TP
  230. .B /adm/netkeys
  231. Encrypted key file for the SecureNet database.
  232. .TP
  233. .B /adm/keys.who
  234. List of users in the Plan 9 database.
  235. .TP
  236. .B /adm/netkeys.who
  237. List of users in the SecureNet database.
  238. .TP
  239. .B #r/nvram
  240. The non-volatile RAM on the server, which holds the key used
  241. to decrypt key files.
  242. .SH SOURCE
  243. .B /sys/src/cmd/auth/keyfs.c
  244. .br
  245. .B /sys/src/cmd/auth/warning.c
  246. .SH "SEE ALSO"
  247. .IR authsrv (6),
  248. .IR namespace (6),
  249. .IR auth (8)