| blob | 507eec881c6a2b0e628f1de24d891eacebe11347 |
1 .\" $NetBSD: kauth.9,v 1.88 2009/08/10 22:36:37 wiz Exp $
2 .\"
3 .\" Copyright (c) 2005, 2006 Elad Efrat <elad@NetBSD.org>
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. The name of the author may not be used to endorse or promote products
15 .\" derived from this software without specific prior written permission.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .Dd August 10, 2009
29 .Dt KAUTH 9
30 .Os
31 .Sh NAME
32 .Nm kauth
33 .Nd kernel authorization framework
34 .Sh SYNOPSIS
35 .In sys/kauth.h
36 .Sh DESCRIPTION
37 .Nm ,
38 or kernel authorization, is the subsystem managing all authorization requests
39 inside the kernel.
40 It manages user credentials and rights, and can be used
41 to implement a system-wide security policy.
42 It allows external modules to plug-in the authorization process.
43 .Pp
44 .Nm
45 introduces some new concepts, namely
46 .Dq scopes
47 and
48 .Dq listeners ,
49 which will be detailed together with other useful information for kernel
50 developers in this document.
51 .Ss Types
52 Some
53 .Nm
54 types include the following:
55 .Bl -tag -width kauth_listener_t
56 .It kauth_cred_t
57 Representing credentials that can be associated with an object.
58 Includes user- and group-ids (real, effective, and save) as well as group
59 membership information.
60 .It kauth_scope_t
61 Describes a scope.
62 .It kauth_listener_t
63 Describes a listener.
64 .El
65 .Ss Terminology
66 .Nm
67 operates in various
68 .Dq scopes ,
69 each scope holding a group of
70 .Dq listeners .
71 .Pp
72 Each listener works as a callback for when an authorization request within the
73 scope is made.
74 When such a request is made, all listeners on the scope are passed common
75 information such as the credentials of the request context, an identifier for
76 the requested operation, and possibly other information as well.
77 .Pp
78 Every listener examines the passed information and returns its decision
79 regarding the requested operation.
80 It can either allow, deny, or defer the operation -- in which case, the
81 decision is left to the other listeners.
82 .Pp
83 For an operation to be allowed, all listeners must not return any deny
84 or defer decisions.
85 .Pp
86 Scopes manage listeners that operate in the same aspect of the system.
87 .Ss Kernel Programming Interface
88 .Nm
89 exports a KPI that allows developers both of
90 .Nx
91 and third-party products to authorize requests, access and modify credentials,
92 create and remove scopes and listeners, and perform other miscellaneous operations on
93 credentials.
94 .Ss Authorization Requests
95 .Nm
96 provides a single authorization request routine, which all authorization
97 requests go through.
98 This routine dispatches the request to the listeners of the appropriate scope,
99 together with four optional user-data variables, and returns the augmented
100 result.
101 .Pp
102 It is declared as
103 .Pp
104 .Ft int Fn kauth_authorize_action "kauth_scope_t scope" "kauth_cred_t cred" \
105 "kauth_action_t op" "void *arg0" "void *arg1" "void *arg2" "void *arg3"
106 .Pp
107 An authorization request can return one of two possible values.
108 Zero indicates success -- the operation is allowed;
109 .Er EPERM
110 (see
111 .Xr errno 2 )
112 indicates failure -- the operation is denied.
113 .Pp
114 Each scope has its own authorization wrapper, to make it easy to call from various
115 places by eliminating the need to specify the scope and/or cast values.
116 The authorization wrappers are detailed in each scope's section.
117 .Pp
118 .Fn kauth_authorize_action
119 has several special cases, when it will always allow the request.
120 These are for when the request is issued by the kernel itself (indicated by the
121 credentials being either
122 .Dv NOCRED
123 or
124 .Dv FSCRED ) ,
125 or when there was no definitive decision from any of the listeners (i.e., it
126 was not explicitly allowed or denied) and no security model was loaded.
127 .Ss Generic Scope
128 The generic scope,
129 .Dq org.netbsd.kauth.generic ,
130 manages generic authorization requests in the kernel.
131 .Pp
132 The authorization wrapper for this scope is declared as
133 .Pp
134 .Ft int Fn kauth_authorize_generic "kauth_cred_t cred" "kauth_action_t op" \
135 "void *arg0"
136 .Pp
137 The following operations are available for this scope:
138 .Bl -tag -width compact
139 .It Dv KAUTH_GENERIC_ISSUSER
140 Checks whether the credentials belong to the super-user.
141 .Pp
142 Using this request is strongly discouraged and should only be done as a
143 temporary place-holder, as it is breaking the separation between the
144 interface for authorization requests from the back-end implementation.
145 .It Dv KAUTH_GENERIC_CANSEE
146 Checks whether an object with one set of credentials can access
147 information about another object, possibly with a different set of
148 credentials.
149 .Pp
150 .Ar arg0
151 contains the credentials of the object looked at.
152 .Pp
153 This request should be issued only in cases where generic credentials
154 check is required; otherwise it is recommended to use the object-specific
155 routines.
156 .El
157 .Ss System Scope
158 The system scope,
159 .Dq org.netbsd.kauth.system ,
160 manages authorization requests affecting the entire system.
161 .Pp
162 The authorization wrapper for this scope is declared as
163 .Pp
164 .Ft int Fn kauth_authorize_system "kauth_cred_t cred" \
165 "kauth_action_t op" "enum kauth_system_req req" "void *arg1" "void *arg2" \
166 "void *arg3"
167 .Pp
168 The following requests are available for this scope:
169 .Bl -tag -width compact
170 .It Dv KAUTH_SYSTEM_ACCOUNTING
171 Check if enabling/disabling accounting allowed.
172 .It Dv KAUTH_SYSTEM_CHROOT
173 .Ar req
174 can be any of the following:
175 .Bl -tag -width compact
176 .It Dv KAUTH_REQ_SYSTEM_CHROOT_CHROOT
177 Check if calling
178 .Xr chroot 2
179 is allowed.
180 .It Dv KAUTH_REQ_SYSTEM_CHROOT_FCHROOT
181 Check if calling
182 .Xr fchroot 2
183 is allowed.
184 .El
185 .It Dv KAUTH_SYSTEM_CPU
186 Check CPU-manipulation access.
187 .Pp
188 .Ar req
189 can be any of the following:
190 .Bl -tag -width compact
191 .It Dv KAUTH_REQ_SYSTEM_CPU_SETSTATE
192 Set CPU state, including setting it online or offline.
193 .El
194 .It Dv KAUTH_SYSTEM_DEBUG
195 This request concentrates several debugging-related operations.
196 .Ar req
197 can be any of the following:
198 .Bl -tag -width compact
199 .It Dv KAUTH_REQ_SYSTEM_DEBUG_IPKDB
200 Check if using
201 .Xr ipkdb 4
202 is allowed.
203 .El
204 .It Dv KAUTH_SYSTEM_FILEHANDLE
205 Check if filehandle operations allowed.
206 .It Dv KAUTH_SYSTEM_FS_QUOTA
207 Check if file-system quota operations are allowed.
208 .Pp
209 .Ar arg1
210 is a
211 .Ft struct mount *
212 describing the file-system mount in question.
213 .Ar req
214 can be one of the following:
215 .Bl -tag -width compact
216 .It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_GET
217 Check if retrieving quota information is allowed.
218 .Pp
219 .Ar arg2
220 is a
221 .Ft uid_t
222 with the user-id of the user whose quota information is to be retrieved.
223 .It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_ONOFF
224 Check if turning quota on/off is allowed.
225 .It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_MANAGE
226 Check if managing the quota by setting the quota/quota use is allowed.
227 .Pp
228 .Ar arg2
229 is a
230 .Ft uid_t
231 with the user-id of the user whose quota/quota use is to be set.
232 .It Dv KAUTH_REQ_SYSTEM_FS_QUOTA_NOLIMIT
233 Check if bypassing the quota (not enforcing it) is allowed.
234 .El
235 .It Dv KAUTH_SYSTEM_FS_RESERVEDSPACE
236 Check if using the file-system reserved space is allowed.
237 .It Dv KAUTH_SYSTEM_MODULE
238 Check if a module request is allowed.
239 .Pp
240 .Ar arg1
241 is the command.
242 .It Dv KAUTH_SYSTEM_MKNOD
243 Check if creating devices is allowed.
244 .It Dv KAUTH_SYSTEM_MOUNT
245 Check if mount-related operations are allowed.
246 .Pp
247 .Ar req
248 can be any of the following:
249 .Bl -tag -width compact
250 .It Dv KAUTH_REQ_SYSTEM_MOUNT_GET
251 Check if retrieving information about a mount is allowed.
252 .Ar arg1
253 is a
254 .Ft struct mount *
255 with the mount structure in question,
256 .Ar arg2
257 is a
258 .Ft void *
259 with file-system specific data, if any.
260 .It Dv KAUTH_REQ_SYSTEM_MOUNT_NEW
261 Check if mounting a new file-system is allowed.
262 .Pp
263 .Ar arg1
264 is the
265 .Ft struct vnode *
266 on which the file-system is to be mounted,
267 .Ar arg2
268 is an
269 .Ft int
270 with the mount flags, and
271 .Ar arg3
272 is a
273 .Ft void *
274 with file-system specific data, if any.
275 .It Dv KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT
276 Checks if unmounting a file-system is allowed.
277 .Pp
278 .Ar arg1
279 is a
280 .Ft struct mount *
281 with the mount in question.
282 .It Dv KAUTH_REQ_SYSTEM_MOUNT_UPDATE
283 Checks if updating an existing mount is allowed.
284 .Pp
285 .Ar arg1
286 is the
287 .Ft struct mount *
288 of the existing mount,
289 .Ar arg2
290 is an
291 .Ft int
292 with the new mount flags, and
293 .Ar arg3
294 is a
295 .Ft void *
296 with file-system specific data, if any.
297 .El
298 .It Dv KAUTH_SYSTEM_PSET
299 Check processor-set manipulation.
300 .Pp
301 .Ar req
302 can be any of the following:
303 .Bl -tag -width compact
304 .It Dv KAUTH_REQ_SYSTEM_PSET_ASSIGN
305 Change processor-set processor assignment.
306 .It Dv KAUTH_REQ_SYSTEM_PSET_BIND
307 Bind an LWP to a processor-set.
308 .It Dv KAUTH_REQ_SYSTEM_PSET_CREATE
309 Create a processor-set.
310 .It Dv KAUTH_REQ_SYSTEM_PSET_DESTROY
311 Destroy a processor-set.
312 .El
313 .It Dv KAUTH_SYSTEM_REBOOT
314 Check if rebooting is allowed.
315 .It Dv KAUTH_SYSTEM_SETIDCORE
316 Check if changing coredump settings for set-id processes is allowed.
317 .It Dv KAUTH_SYSTEM_SWAPCTL
318 Check if privileged
319 .Xr swapctl 2
320 requests are allowed.
321 .It Dv KAUTH_SYSTEM_SYSCTL
322 This requests operations related to
323 .Xr sysctl 9 .
324 .Ar req
325 indicates the specific request and can be one of the following:
326 .Bl -tag -width compact
327 .It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD
328 Check if adding a
329 .Xr sysctl 9
330 node is allowed.
331 .It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE
332 Check if deleting a
333 .Xr sysctl 9
334 node is allowed.
335 .It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC
336 Check if adding description to a
337 .Xr sysctl 9
338 node is allowed.
339 .It Dv KAUTH_REQ_SYSTEM_SYSCTL_MODIFY
340 Check if modifying a
341 .Xr sysctl 9
342 node variable that doesn't have a custom sysctl helper function is allowed.
343 .Pp
344 This request might be deprecated in the future.
345 .It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT
346 Check if accessing private
347 .Xr sysctl 9
348 nodes is allowed.
349 .El
350 .It Dv KAUTH_SYSTEM_TIME
351 This request groups time-related operations.
352 .Ar req
353 can be any of the following:
354 .Bl -tag -width compact
355 .It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME
356 Check if changing the time using
357 .Xr adjtime 2
358 is allowed.
359 .It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME
360 Check if setting the time using
361 .Xr ntp_adjtime 2
362 is allowed.
363 .It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM
364 Check if changing the time (usually via
365 .Xr settimeofday 2 )
366 is allowed.
367 .Pp
368 .Ar arg1
369 is a
370 .Ft struct timespec *
371 with the new time,
372 .Ar arg2
373 is a
374 .Ft struct timeval *
375 with the delta from the current time,
376 .Ar arg3
377 is a
378 .Ft bool
379 indicating whether the caller is a device context (e.g.
380 .Pa /dev/clockctl )
381 or not.
382 .It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET
383 Check if changing the RTC offset is allowed.
384 .It Dv KAUTH_REQ_SYSTEM_TIME_TIMECOUNTERS
385 Check if manipulating timecounters is allowed.
386 .El
387 .El
388 .Ss Process Scope
389 The process scope,
390 .Dq org.netbsd.kauth.process ,
391 manages authorization requests related to processes in the system.
392 .Pp
393 The authorization wrapper for this scope is declared as
394 .Pp
395 .Ft int Fn kauth_authorize_process "kauth_cred_t cred" \
396 "kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \
397 "void *arg3"
398 .Pp
399 The following operations are available for this scope:
400 .Bl -tag -width compact
401 .It Dv KAUTH_PROCESS_KTRACE
402 Checks whether an object with one set of credentials can
403 .Xr ktrace 1
404 another process
405 .Ar p ,
406 possibly with a different set of credentials.
407 .Pp
408 If
409 .Ar arg1
410 is
411 .Dv KAUTH_REQ_PROCESS_KTRACE_PERSISTENT ,
412 this checks if persistent tracing can be done.
413 Persistent tracing maintains the trace across a set-user-id/set-group-id
414 .Xr exec 3 ,
415 and normally requires privileged credentials.
416 .It Dv KAUTH_PROCESS_PROCFS
417 Checks whether object with passed credentials can use
418 .Em procfs
419 to access process
420 .Ar p .
421 .Pp
422 .Ar arg1
423 is the
424 .Ft struct pfsnode *
425 for the target element in the target process, and
426 .Ar arg2
427 is the access type, which can be either
428 .Dv KAUTH_REQ_PROCESS_PROCFS_CTL ,
429 .Dv KAUTH_REQ_PROCESS_PROCFS_READ ,
430 .Dv KAUTH_REQ_PROCESS_PROCFS_RW ,
431 or
432 .Dv KAUTH_REQ_PROCESS_PROCFS_WRITE ,
433 indicating
434 .Em control ,
435 .Em read ,
436 .Em read-write ,
437 or
438 .Em write
439 access respectively.
440 .It Dv KAUTH_PROCESS_PTRACE
441 Checks whether object with passed credentials can use
442 .Xr ptrace 2
443 to access process
444 .Ar p .
445 .Pp
446 .Ar arg1
447 is the
448 .Xr ptrace 2
449 command.
450 .It Dv KAUTH_PROCESS_CANSEE
451 Checks whether an object with one set of credentials can access
452 information about another process, possibly with a different set of
453 credentials.
454 .Pp
455 .Ar arg1
456 indicates the class of information being viewed, and can either of
457 .Dv KAUTH_REQ_PROCESS_CANSEE_ARGS ,
458 .Dv KAUTH_REQ_PROCESS_CANSEE_ENTRY ,
459 .Dv KAUTH_REQ_PROCESS_CANSEE_ENV ,
460 or
461 .Dv KAUTH_REQ_PROCESS_CANSEE_OPENFILES .
462 .It Dv KAUTH_PROCESS_SCHEDULER_GETAFFINITY
463 Checks whether viewing the scheduler affinity is allowed.
464 .It Dv KAUTH_PROCESS_SCHEDULER_SETAFFINITY
465 Checks whether setting the scheduler affinity is allowed.
466 .It Dv KAUTH_PROCESS_SCHEDULER_GETPARAMS
467 Checks whether viewing the scheduler policy and parameters is allowed.
468 .It Dv KAUTH_PROCESS_SCHEDULER_SETPARAMS
469 Checks whether modifying the scheduler policy and parameters is allowed.
470 .It Dv KAUTH_PROCESS_SIGNAL
471 Checks whether an object with one set of credentials can post signals
472 to another process.
473 .Pp
474 .Ar p
475 is the process the signal is being posted to, and
476 .Ar arg1
477 is the signal number.
478 .It Dv KAUTH_PROCESS_CORENAME
479 Controls access to process corename.
480 .Pp
481 .Ar arg1
482 can be
483 .Dv KAUTH_REQ_PROCESS_CORENAME_GET
484 or
485 .Dv KAUTH_REQ_PROCESS_CORENAME_SET ,
486 indicating access to read or write the process' corename, respectively.
487 .Pp
488 When modifying the corename,
489 .Ar arg2
490 holds the new corename to be used.
491 .It Dv KAUTH_PROCESS_FORK
492 Checks if the process can fork.
493 .Ar arg1
494 is an
495 .Ft int
496 indicating how many processes exist on the system at the time of the check.
497 .It Dv KAUTH_PROCESS_KEVENT_FILTER
498 Checks whether setting a process
499 .Xr kevent 2
500 filter is allowed.
501 .Pp
502 .It Dv KAUTH_PROCESS_NICE
503 Checks whether the
504 .Em nice
505 value of
506 .Ar p
507 can be changed to
508 .Ar arg1 .
509 .It Dv KAUTH_PROCESS_RLIMIT
510 Controls access to process resource limits.
511 .Pp
512 .Ar arg1
513 can be
514 .Dv KAUTH_REQ_PROCESS_RLIMIT_GET
515 or
516 .Dv KAUTH_REQ_PROCESS_RLIMIT_SET ,
517 indicating access to read or write the process' resource limits, respectively.
518 .Pp
519 When modifying resource limits,
520 .Ar arg2
521 is the new value to be used and
522 .Ar arg3
523 indicates which resource limit is to be modified.
524 .It Dv KAUTH_PROCESS_SETID
525 Check if changing the user- or group-ids, groups, or login-name for
526 .Ar p
527 is allowed.
528 .It Dv KAUTH_PROCESS_STOPFLAG
529 Check if setting the stop flags for
530 .Xr exec 3 ,
531 .Xr exit 3 ,
532 and
533 .Xr fork 2
534 is allowed.
535 .Pp
536 .Ar arg1
537 indicates the flag, and can be either
538 .Dv P_STOPEXEC ,
539 .Dv P_STOPEXIT ,
540 or
541 .Dv P_STOPFORK
542 respectively.
543 .El
544 .Ss Network Scope
545 The network scope,
546 .Dq org.netbsd.kauth.network ,
547 manages networking-related authorization requests in the kernel.
548 .Pp
549 The authorization wrapper for this scope is declared as
550 .Pp
551 .Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \
552 "enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3"
553 .Pp
554 The following operations are available for this scope:
555 .Bl -tag -width compact
556 .It Dv KAUTH_NETWORK_ALTQ
557 Checks if an ALTQ operation is allowed.
558 .Pp
559 .Ar req
560 indicates the ALTQ subsystem in question, and can be one of the following:
561 .Pp
562 .Bl -tag -compact -width compact
563 .It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP
564 .It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE
565 .It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ
566 .It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR
567 .It Dv KAUTH_REQ_NETWORK_ALTQ_CONF
568 .It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ
569 .It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC
570 .It Dv KAUTH_REQ_NETWORK_ALTQ_JOBS
571 .It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ
572 .It Dv KAUTH_REQ_NETWORK_ALTQ_RED
573 .It Dv KAUTH_REQ_NETWORK_ALTQ_RIO
574 .It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ
575 .El
576 .It Dv KAUTH_NETWORK_BIND
577 Checks if a
578 .Xr bind 2
579 request is allowed.
580 .Pp
581 .Ar req
582 allows to indicate the type of the request to structure listeners and callers
583 easier.
584 Supported request types:
585 .Bl -tag -width compact
586 .It Dv KAUTH_REQ_NETWORK_BIND_PORT
587 Checks if binding to a non-privileged/reserved port is allowed.
588 .It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT
589 Checks if binding to a privileged/reserved port is allowed.
590 .El
591 .It Dv KAUTH_NETWORK_FIREWALL
592 Checks if firewall-related operations are allowed.
593 .Pp
594 .Ar req
595 indicates the sub-action, and can be one of the following:
596 .Bl -tag -width compact
597 .It Dv KAUTH_REQ_NETWORK_FIREWALL_FW
598 Modification of packet filtering rules.
599 .It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT
600 Modification of NAT rules.
601 .El
602 .It Dv KAUTH_NETWORK_INTERFACE
603 Checks if network interface-related operations are allowed.
604 .Pp
605 .Ar arg1
606 is (optionally) the
607 .Ft struct ifnet *
608 associated with the interface.
609 .Ar arg2
610 is (optionally) an
611 .Ft int
612 describing the interface-specific operation.
613 .Ar arg3
614 is (optionally) a pointer to the interface-specific request structure.
615 .Ar req
616 indicates the sub-action, and can be one of the following:
617 .Bl -tag -width compact
618 .It Dv KAUTH_REQ_NETWORK_INTERFACE_GET
619 Check if retrieving information from the device is allowed.
620 .It Dv KAUTH_REQ_NETWORK_INTERFACE_GETPRIV
621 Check if retrieving privileged information from the device is allowed.
622 .It Dv KAUTH_REQ_NETWORK_INTERFACE_SET
623 Check if setting parameters on the device is allowed.
624 .It Dv KAUTH_REQ_NETWORK_INTERFACE_SETPRIV
625 Check if setting privileged parameters on the device is allowed.
626 .El
627 .Pp
628 Note that unless the
629 .Ft struct ifnet *
630 for the interface was passed in
631 .Ar arg1 ,
632 there's no way to tell what structure
633 .Ar arg3
634 is.
635 .It Dv KAUTH_NETWORK_INTERFACE_PPP
636 Checks if operations performed on the
637 .Xr ppp 4
638 network interface are allowed.
639 .Pp
640 .Ar req
641 can be one of the following:
642 .Bl -tag -width compact
643 .It Dv KAUTH_REQ_NETWORK_INTERFACE_PPP_ADD
644 Checks if adding and enabling a
645 .Xr ppp 4
646 interface to the system is allowed.
647 .El
648 .It Dv KAUTH_NETWORK_INTERFACE_SLIP
649 Checks if operations performed on the
650 .Xr sl 4
651 network interface are allowed.
652 .Pp
653 .Ar req
654 can be one of the following:
655 .Bl -tag -width compact
656 .It Dv KAUTH_REQ_NETWORK_INTERFACE_SLIP_ADD
657 Checks if adding and enabling a
658 .Xr sl 4
659 interface to the system is allowed.
660 .El
661 .It Dv KAUTH_NETWORK_INTERFACE_STRIP
662 Checks if operations performed on the
663 .Xr strip 4
664 network interface are allowed.
665 .Pp
666 .Ar req
667 can be one of the following:
668 .Bl -tag -width compact
669 .It Dv KAUTH_REQ_NETWORK_INTERFACE_STRIP_ADD
670 Check if adding and enabling a
671 .Xr strip 4
672 interface to the system is allowed.
673 .El
674 .It Dv KAUTH_NETWORK_INTERFACE_TUN
675 Checks if operations performed on the
676 .Xr tun 4
677 network interface are allowed.
678 .Pp
679 .Ar req
680 can be one of the following:
681 .Bl -tag -width compact
682 .It Dv KAUTH_REQ_NETWORK_INTERFACE_TUN_ADD
683 Checks if adding and enabling a
684 .Xr tun 4
685 interface to the system is allowed.
686 .El
687 .It Dv KAUTH_NETWORK_FORWSRCRT
688 Checks whether status of forwarding of source-routed packets can be modified
689 or not.
690 .It Dv KAUTH_NETWORK_NFS
691 Check is an NFS related operation is allowed.
692 .Pp
693 .Ar req
694 can be any of the following:
695 .Bl -tag -width compact
696 .It Dv KAUTH_REQ_NETWORK_NFS_EXPORT
697 Check if modifying the NFS export table is allowed.
698 .It Dv KAUTH_REQ_NETWORK_NFS_SVC
699 Check if access to the NFS
700 .Xr nfssvc 2
701 syscall is allowed.
702 .El
703 .It Dv KAUTH_NETWORK_ROUTE
704 Checks if a routing-related request is allowed.
705 .Pp
706 .Ar arg1
707 is the
708 .Ft struct rt_msghdr *
709 for the request.
710 .It Dv KAUTH_NETWORK_SOCKET
711 Checks if a socket related operation is allowed.
712 .Pp
713 .Ar req
714 allows to indicate the type of the request to structure listeners and callers
715 easier.
716 Supported request types:
717 .Bl -tag -width compact
718 .It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK
719 Checks if opening a raw socket is allowed.
720 .It Dv KAUTH_REQ_NETWORK_SOCKET_OPEN
721 Checks if opening a socket is allowed.
722 .Ar arg1 , arg2 ,
723 and
724 .Ar arg3
725 are all
726 .Ft int
727 parameters describing the domain, socket type, and protocol,
728 respectively.
729 .It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE
730 Checks if looking at the socket passed is allowed.
731 .Pp
732 .Ar arg1
733 is a
734 .Ft struct socket *
735 describing the socket.
736 .It Dv KAUTH_REQ_NETWORK_SOCKET_DROP
737 Checks if a connection can be dropped.
738 .Pp
739 .Ar arg1
740 is a
741 .Ft struct socket *
742 describing the socket.
743 .It Dv KAUTH_REQ_NETWORK_SOCKET_SETPRIV
744 Checks if setting privileged socket options is allowed.
745 .Pp
746 .Ar arg1
747 is a
748 .Ft struct socket *
749 describing the socket,
750 .Ar arg2
751 is a
752 .Ft u_long
753 describing the socket option.
754 .El
755 .El
756 .Ss Machine-dependent Scope
757 The machine-dependent (machdep) scope,
758 .Dq org.netbsd.kauth.machdep ,
759 manages machine-dependent authorization requests in the kernel.
760 .Pp
761 The authorization wrapper for this scope is declared as
762 .Pp
763 .Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \
764 "void *arg0" "void *arg1" "void *arg2" "void *arg3"
765 .Pp
766 The actions on this scope provide a set that may or may not affect all
767 platforms.
768 Below is a list of available actions, along with which platforms are affected
769 by each.
770 .Bl -tag -width compact
771 .It Dv KAUTH_MACHDEP_CACHEFLUSH
772 Request to flush the whole CPU cache.
773 Affects
774 .Em m68k
775 Linux emulation.
776 .It Dv KAUTH_MACHDEP_IOPERM_GET
777 Request to get the I/O permission level.
778 Affects
779 .Em amd64 ,
780 .Em i386 ,
781 .Em xen .
782 .It Dv KAUTH_MACHDEP_IOPERM_SET
783 Request to set the I/O permission level.
784 Affects
785 .Em amd64 ,
786 .Em i386 ,
787 .Em xen .
788 .It Dv KAUTH_MACHDEP_IOPL
789 Request to set the I/O privilege level.
790 Affects
791 .Em amd64 ,
792 .Em i386 ,
793 .Em xen .
794 .It Dv KAUTH_MACHDEP_LDT_GET
795 Request to get the LDT (local descriptor table).
796 Affects
797 .Em amd64 ,
798 .Em i386 ,
799 .Em xen .
800 .It Dv KAUTH_MACHDEP_LDT_SET
801 Request to set the LDT (local descriptor table).
802 Affects
803 .Em amd64 ,
804 .Em i386 ,
805 .Em xen .
806 .It Dv KAUTH_MACHDEP_MTRR_GET
807 Request to get the MTRR (memory type range registers).
808 Affects
809 .Em amd64 ,
810 .Em i386 ,
811 .Em xen .
812 .It Dv KAUTH_MACHDEP_MTRR_SET
813 Request to set the MTRR (memory type range registers).
814 Affects
815 .Em amd64 ,
816 .Em i386 ,
817 .Em xen .
818 .It Dv KAUTH_MACHDEP_NVRAM
819 Request to access (read/write) the NVRAM.
820 Affects
821 .Em i386 .
822 .It Dv KAUTH_MACHDEP_UNMANAGEDMEM
823 Request to access unmanaged memory.
824 Affects
825 .Em alpha ,
826 .Em amd64 ,
827 .Em arm ,
828 .Em i386 ,
829 .Em powerpc ,
830 .Em sh3 ,
831 .Em vax ,
832 .Em xen .
833 .El
834 .Ss Device Scope
835 The device scope,
836 .Dq org.netbsd.kauth.device ,
837 manages authorization requests related to devices on the system.
838 Devices can be, for example, terminals, tape drives, Bluetooth accessories, and
839 any other hardware.
840 Network devices specifically are handled by the
841 .Em network
842 scope.
843 .Pp
844 In addition to the standard authorization wrapper:
845 .Pp
846 .Ft int Fn kauth_authorize_device "kauth_cred_t cred" "kauth_action_t op" \
847 "void *arg0" "void *arg1" "void *arg2" "void *arg3"
848 .Pp
849 this scope provides authorization wrappers for various device types.
850 .Pp
851 .Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \
852 "struct tty *tty"
853 .Pp
854 Authorizes requests for
855 .Em terminal devices
856 on the system.
857 The third argument,
858 .Ar tty ,
859 is the terminal device in question.
860 It is passed to the listener as
861 .Ar arg0 .
862 The second argument,
863 .Ar op ,
864 is the action and can be one of the following:
865 .Bl -tag -width compact
866 .It Dv KAUTH_DEVICE_TTY_OPEN
867 Open the terminal device pointed to by
868 .Ar tty .
869 .It Dv KAUTH_DEVICE_TTY_PRIVSET
870 Set privileged settings on the terminal device pointed to by
871 .Ar tty .
872 .It Dv KAUTH_DEVICE_TTY_STI
873 Use the
874 .Dq TIOCSTI
875 device
876 .Xr ioctl 2 ,
877 allowing to inject characters into the terminal buffer, simulating terminal
878 input.
879 .El
880 .Pp
881 .Ft int Fn kauth_authorize_device_spec "kauth_cred_t cred" \
882 "enum kauth_device_req req" "struct vnode *vp"
883 .Pp
884 Authorizes requests for
885 .Em special files ,
886 usually disk devices, but also direct memory access, on the system.
887 .Pp
888 It passes
889 .Dv KAUTH_DEVICE_RAWIO_SPEC
890 as the action to the listener, and accepts two arguments.
891 .Ar req ,
892 passed to the listener as
893 .Ar arg0 ,
894 is access requested, and can be one of
895 .Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_READ ,
896 .Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE ,
897 or
898 .Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_RW ,
899 representing read, write, or both read/write access respectively.
900 .Ar vp
901 is the vnode of the special file in question, and is passed to the listener as
902 .Ar arg1 .
903 .Pp
904 Keep in mind that it is the responsibility of the security model developer to
905 check whether the underlying device is a disk or the system memory, using
906 .Fn iskmemdev :
907 .Bd -literal -offset indent
908 if ((vp-\*[Gt]v_type == VCHR) \*[Am]\*[Am]
909 iskmemdev(vp-\*[Gt]v_un.vu_specinfo-\*[Gt]si_rdev))
910 /* system memory access */
911 .Ed
912 .Pp
913 .Ft int Fn kauth_authorize_device_passthru "kauth_cred_t cred" "dev_t dev" \
914 "u_long mode" "void *data"
915 .Pp
916 Authorizes hardware
917 .Em passthru
918 requests, or user commands passed directly to the hardware.
919 These have the potential of resulting in direct disk and/or memory access.
920 .Pp
921 It passes
922 .Dv KAUTH_DEVICE_RAWIO_PASSTHRU
923 as the action to the listener, and accepts three arguments.
924 .Ar dev ,
925 passed as
926 .Ar arg1
927 to the listener, is the device for which the request is made.
928 .Ar mode ,
929 passed as
930 .Ar arg0
931 to the listener, is a generic representation of the access mode requested.
932 It can be one or more (binary-OR'd) of the following:
933 .Pp
934 .Bl -tag -width compact -offset indent -compact
935 .It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ
936 .It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF
937 .It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE
938 .It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF
939 .El
940 .Pp
941 .Ar data ,
942 passed as
943 .Ar arg2
944 to the listener, is device-specific data that may be associated with the
945 request.
946 .Ss Bluetooth Devices
947 Authorizing actions relevant to Bluetooth devices is done using the standard
948 authorization wrapper, with the following actions:
949 .Pp
950 .Bl -tag -width compact
951 .It KAUTH_DEVICE_BLUETOOTH_BCSP
952 Check if operations on a
953 .Xr bcsp 4
954 device are allowed.
955 .Pp
956 .Ar arg0
957 is an
958 .Ft enum kauth_device_req
959 with one of the following values:
960 .Bl -tag -width compact
961 .It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BCSP_ADD
962 Check if adding and enabling a
963 .Xr bcsp 4
964 device is allowed.
965 .El
966 .It KAUTH_DEVICE_BLUETOOTH_BTUART
967 Check if operations on a
968 .Xr btuart 4
969 device are allowed.
970 .Pp
971 .Ar arg0
972 is an
973 .Ft enum kauth_device_req
974 with one of the following values:
975 .Bl -tag -width compact
976 .It Dv KAUTH_REQ_DEVICE_BLUETOOTH_BTUART_ADD
977 Check if adding and enabling a
978 .Xr btuart 4
979 device is allowed.
980 .El
981 .It KAUTH_DEVICE_BLUETOOTH_RECV
982 Check if a packet can be received from the device.
983 .Pp
984 .Ar arg0
985 is the packet type.
986 For
987 .Dv HCI_CMD_PKT
988 packets,
989 .Ar arg1
990 is the opcode, for
991 .Dv HCI_EVENT_PKT
992 packets,
993 .Ar arg1
994 is the event ID, and for
995 .Dv HCI_ACLDATA_PKT
996 or
997 .Dv HCI_SCODATA_PKT
998 packets,
999 .Ar arg1
1000 is the connection handle.
1001 .It KAUTH_DEVICE_BLUETOOTH_SEND
1002 Check if a packet can be sent to the device.
1003 .Pp
1004 .Ar arg0
1005 is a
1006 .Ft struct hci_unit *
1007 describing the HCI unit,
1008 .Ar arg1
1009 is a
1010 .Ft hci_cmd_hdr_t *
1011 describing the packet header.
1012 .It KAUTH_DEVICE_BLUETOOTH_SETPRIV
1013 Check if privileged settings can be changed.
1014 .Pp
1015 .Ar arg0
1016 is a
1017 .Ft struct hci_unit *
1018 describing the HCI unit,
1019 .Ar arg1
1020 is a
1021 .Ft struct btreq *
1022 describing the request, and
1023 .Ar arg2
1024 is a
1025 .Ft u_long
1026 describing the command.
1027 .El
1028 .Ss Kernel random device
1029 Authorization actions relevant to the kernel random device,
1030 .Xr rnd 4 ,
1031 is done using the standard authorization wrapper, with the following actions:
1032 .Pp
1033 .Bl -tag -width compact
1034 .It KAUTH_DEVICE_RND_ADDDATA
1035 Check if adding data to the entropy pool is allowed.
1036 .It KAUTH_DEVICE_RND_GETPRIV
1037 Check if privileged settings and information can be retrieved.
1038 .It KAUTH_DEVICE_RND_SETPRIV
1039 Check if privileged settings can be changed.
1040 .El
1041 .Ss Credentials Scope
1042 The credentials scope,
1043 .Dq org.netbsd.kauth.cred ,
1044 is a special scope used internally by the
1045 .Nm
1046 framework to provide hooking to credential-related operations.
1047 .Pp
1048 It is a
1049 .Dq notify-only
1050 scope, allowing hooking operations such as initialization of new credentials,
1051 credential inheritance during a fork, and copying and freeing of credentials.
1052 The main purpose for this scope is to give a security model a way to control
1053 the aforementioned operations, especially in cases where the credentials
1054 hold security model-private data.
1055 .Pp
1056 Notifications are made using the following function, which is internal to
1057 .Nm :
1058 .Pp
1059 .Ft int Fn kauth_cred_hook "kauth_cred_t cred" "kauth_action_t action" \
1060 "void *arg0" "void *arg1"
1061 .Pp
1062 With the following actions:
1063 .Bl -tag -width compact
1064 .It Dv KAUTH_CRED_COPY
1065 The credentials are being copied.
1066 .Ar cred
1067 are the credentials of the lwp context doing the copy, and
1068 .Ar arg0
1069 and
1070 .Ar arg1
1071 are both
1072 .Ft kauth_cred_t
1073 representing the
1074 .Dq from
1075 and
1076 .Dq to
1077 credentials, respectively.
1078 .It Dv KAUTH_CRED_FORK
1079 The credentials are being inherited from a parent to a child process during a
1080 fork.
1081 .Pp
1082 .Ar cred
1083 are the credentials of the lwp context doing the fork, and
1084 .Ar arg0
1085 and
1086 .Ar arg1
1087 are both
1088 .Ft struct proc *
1089 of the parent and child processes, respectively.
1090 .It Dv KAUTH_CRED_FREE
1091 The credentials in
1092 .Ar cred
1093 are being freed.
1094 .It Dv KAUTH_CRED_INIT
1095 The credentials in
1096 .Ar cred
1097 are being initialized.
1098 .El
1099 .Pp
1100 Since this is a notify-only scope, all listeners are required to return
1101 .Dv KAUTH_RESULT_ALLOW .
1102 .Ss Credentials Accessors and Mutators
1103 .Nm
1104 has a variety of accessor and mutator routines to handle
1105 .Ft kauth_cred_t
1106 objects.
1107 .Pp
1108 The following routines can be used to access and modify the user- and
1109 group-ids in a
1110 .Ft kauth_cred_t :
1111 .Bl -tag -width compact
1112 .It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred"
1113 Returns the real user-id from
1114 .Ar cred .
1115 .It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred"
1116 Returns the effective user-id from
1117 .Ar cred .
1118 .It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred"
1119 Returns the saved user-id from
1120 .Ar cred .
1121 .It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid"
1122 Sets the real user-id in
1123 .Ar cred
1124 to
1125 .Ar uid .
1126 .It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid"
1127 Sets the effective user-id in
1128 .Ar cred
1129 to
1130 .Ar uid .
1131 .It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid"
1132 Sets the saved user-id in
1133 .Ar cred
1134 to
1135 .Ar uid .
1136 .It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred"
1137 Returns the real group-id from
1138 .Ar cred .
1139 .It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred"
1140 Returns the effective group-id from
1141 .Ar cred .
1142 .It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred"
1143 Returns the saved group-id from
1144 .Ar cred .
1145 .It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid"
1146 Sets the real group-id in
1147 .Ar cred
1148 to
1149 .Ar gid .
1150 .It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid"
1151 Sets the effective group-id in
1152 .Ar cred
1153 to
1154 .Ar gid .
1155 .It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid"
1156 Sets the saved group-id in
1157 .Ar cred
1158 to
1159 .Ar gid .
1160 .It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred"
1161 Return the reference count for
1162 .Ar cred .
1163 .El
1164 .Pp
1165 The following routines can be used to access and modify the group
1166 list in a
1167 .Ft kauth_cred_t :
1168 .Bl -tag -width compact
1169 .It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \
1170 "int *resultp"
1171 Checks if the group-id
1172 .Ar gid
1173 is a member in the group list of
1174 .Ar cred .
1175 .Pp
1176 If it is,
1177 .Ar resultp
1178 will be set to one, otherwise, to zero.
1179 .Pp
1180 The return value is an error code, or zero for success.
1181 .It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred"
1182 Return the number of groups in the group list of
1183 .Ar cred .
1184 .It Ft gid_t Fn kauth_cred_group "kauth_cred_t cred" "u_int idx"
1185 Return the group-id of the group at index
1186 .Ar idx
1187 in the group list of
1188 .Ar cred .
1189 .It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "const gid_t *groups" \
1190 "size_t ngroups" "uid_t gmuid" "enum uio_seg seg"
1191 Copy
1192 .Ar ngroups
1193 groups from array pointed to by
1194 .Ar groups
1195 to the group list in
1196 .Ar cred ,
1197 adjusting the number of groups in
1198 .Ar cred
1199 appropriately.
1200 .Ar seg
1201 should be either
1202 .Dv UIO_USERSPACE
1203 or
1204 .Dv UIO_SYSSPACE
1205 indicating whether
1206 .Ar groups
1207 is a user or kernel space address.
1208 .Pp
1209 Any groups remaining will be set to an invalid value.
1210 .Pp
1211 .Ar gmuid
1212 is unused for now, and to maintain interface compatibility with the Darwin
1213 KPI.
1214 .Pp
1215 The return value is an error code, or zero for success.
1216 .It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \
1217 "size_t ngroups" "enum uio_seg seg"
1218 Copy
1219 .Ar ngroups
1220 groups from the group list in
1221 .Ar cred
1222 to the buffer pointed to by
1223 .Ar groups .
1224 .Ar seg
1225 should be either
1226 .Dv UIO_USERSPACE
1227 or
1228 .Dv UIO_SYSSPACE
1229 indicating whether
1230 .Ar groups
1231 is a user or kernel space address.
1232 .Pp
1233 The return value is an error code, or zero for success.
1234 .El
1235 .Ss Credential Private Data
1236 .Nm
1237 provides an interface to allow attaching security-model private data to
1238 credentials.
1239 .Pp
1240 The use of this interface has two parts that can be divided to direct and
1241 indirect control of the private-data.
1242 Directly controlling the private data is done by using the below routines,
1243 while the indirect control is often dictated by events such as process
1244 fork, and is handled by listening on the credentials scope (see above).
1245 .Pp
1246 Attaching private data to credentials works by registering a key to serve
1247 as a unique identifier, distinguishing various sets of private data that
1248 may be associated with the credentials.
1249 Registering, and deregistering, a key is done by using these routines:
1250 .Pp
1251 .Bl -tag -width compact
1252 .It Ft int Fn kauth_register_key "const char *name" "kauth_key_t *keyp"
1253 Register new key for private data for
1254 .Ar name
1255 (usually, the security model name).
1256 .Ar keyp
1257 will be used to return the key to be used in further calls.
1258 .Pp
1259 The function returns 0 on success and an error code (see
1260 .Xr errno 2 )
1261 on failure.
1262 .It Ft int Fn kauth_deregister_key "kauth_key_t key"
1263 Deregister private data key
1264 .Ar key .
1265 .El
1266 .Pp
1267 Once registered, private data may be manipulated by the following routines:
1268 .Bl -tag -width compact
1269 .It Ft void Fn kauth_cred_setdata "kauth_cred_t cred" "kauth_key_t key" \
1270 "void *data"
1271 Set private data for
1272 .Ar key
1273 in
1274 .Ar cred
1275 to be
1276 .Ar data .
1277 .It Ft void * Fn kauth_cred_getdata "kauth_cred_t cred" "kauth_key_t key"
1278 Retrieve private data for
1279 .Ar key
1280 in
1281 .Ar cred .
1282 .El
1283 .Pp
1284 Note that it is required to use the above routines every time the private
1285 data is changed, i.e., using
1286 .Fn kauth_cred_getdata
1287 and later modifying the private data should be accompanied by a call to
1288 .Fn kauth_cred_setdata
1289 with the
1290 .Dq new
1291 private data.
1292 .Ss Credential Inheritance and Reference Counting
1293 .Nm
1294 provides an interface for handling shared credentials.
1295 .Pp
1296 When a
1297 .Ft kauth_cred_t
1298 is first allocated, its reference count is set to 1.
1299 However, with time, its reference count can grow as more objects (processes,
1300 LWPs, files, etc.) reference it.
1301 .Pp
1302 The following routines are available for managing credentials reference
1303 counting:
1304 .Bl -tag -width compact
1305 .It Ft void Fn kauth_cred_hold "kauth_cred_t cred"
1306 Increases reference count to
1307 .Ar cred
1308 by one.
1309 .It Ft void Fn kauth_cred_free "kauth_cred_t cred"
1310 Decreases the reference count to
1311 .Ar cred
1312 by one.
1313 .Pp
1314 If the reference count dropped to zero, the memory used by
1315 .Ar cred
1316 will be freed.
1317 .El
1318 .Pp
1319 Credential inheritance happens during a
1320 .Xr fork 2 ,
1321 and is handled by the following function:
1322 .Pp
1323 .Ft void Fn kauth_proc_fork "struct proc *parent" "struct proc *child"
1324 .Pp
1325 When called, it references the parent's credentials from the child,
1326 and calls the credentials scope's hook with the
1327 .Dv KAUTH_CRED_FORK
1328 action to allow security model-specific handling of the inheritance
1329 to take place.
1330 .Ss Credentials Memory Management
1331 Data-structures for credentials, listeners, and scopes are allocated from
1332 memory pools managed by the
1333 .Xr pool 9
1334 subsystem.
1335 .Pp
1336 The
1337 .Ft kauth_cred_t
1338 objects have their own memory management routines:
1339 .Bl -tag -width compact
1340 .It Ft kauth_cred_t Fn kauth_cred_alloc "void"
1341 Allocates a new
1342 .Ft kauth_cred_t ,
1343 initializes its lock, and sets its reference count to one.
1344 .El
1345 .Ss Conversion Routines
1346 Sometimes it might be necessary to convert a
1347 .Ft kauth_cred_t
1348 to userland's view of credentials, a
1349 .Ft struct uucred ,
1350 or vice versa.
1351 .Pp
1352 The following routines are available for these cases:
1353 .Bl -tag -width compact
1354 .It Ft void Fn kauth_uucred_to_cred "kauth_cred_t cred" "const struct uucred *uucred"
1355 Convert userland's view of credentials to a
1356 .Ft kauth_cred_t .
1357 .Pp
1358 This includes effective user- and group-ids, a number of groups, and a group
1359 list.
1360 The reference count is set to one.
1361 .Pp
1362 Note that
1363 .Nm
1364 will try to copy as many groups as can be held inside a
1365 .Ft kauth_cred_t .
1366 .It Ft void Fn kauth_cred_to_uucred "struct uucred *uucred" "const kauth_cred_t cred"
1367 Convert
1368 .Ft kauth_cred_t
1369 to userland's view of credentials.
1370 .Pp
1371 This includes effective user- and group-ids, a number of groups, and a group
1372 list.
1373 .Pp
1374 Note that
1375 .Nm
1376 will try to copy as many groups as can be held inside a
1377 .Ft struct uucred .
1378 .It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred"
1379 Compares
1380 .Ar cred
1381 with the userland credentials in
1382 .Ar uucred .
1383 .Pp
1384 Common values that will be compared are effective user- and group-ids, and
1385 the group list.
1386 .El
1387 .Ss Miscellaneous Routines
1388 Other routines provided by
1389 .Nm
1390 are:
1391 .Bl -tag -width compact
1392 .It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2"
1393 Clone credentials from
1394 .Ar cred1
1395 to
1396 .Ar cred2 ,
1397 except for the lock and reference count.
1398 .Pp
1399 .It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred"
1400 Duplicate
1401 .Ar cred .
1402 .Pp
1403 What this routine does is call
1404 .Fn kauth_cred_alloc
1405 followed by a call to
1406 .Fn kauth_cred_clone .
1407 .It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred"
1408 Works like
1409 .Fn kauth_cred_dup ,
1410 except for a few differences.
1411 .Pp
1412 If
1413 .Ar cred
1414 already has a reference count of one, it will be returned.
1415 Otherwise, a new
1416 .Ft kauth_cred_t
1417 will be allocated and the credentials from
1418 .Ar cred
1419 will be cloned to it.
1420 Last, a call to
1421 .Fn kauth_cred_free
1422 for
1423 .Ar cred
1424 will be done.
1425 .It Ft kauth_cred_t Fn kauth_cred_get "void"
1426 Return the credentials associated with the current LWP.
1427 .El
1428 .Ss Scope Management
1429 .Nm
1430 provides routines to manage the creation and deletion of scopes on the
1431 system.
1432 .Pp
1433 Note that the built-in scopes, the
1434 .Dq generic
1435 scope and the
1436 .Dq process
1437 scope, can't be deleted.
1438 .Bl -tag -width compact
1439 .It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \
1440 "kauth_scope_callback_t cb" "void *cookie"
1441 Register a new scope on the system.
1442 .Ar id
1443 is the name of the scope, usually in reverse DNS-like notation.
1444 For example,
1445 .Dq org.netbsd.kauth.myscope .
1446 .Ar cb
1447 is the default listener, to which authorization requests for this scope
1448 will be dispatched to.
1449 .Ar cookie
1450 is optional user-data that will be passed to all listeners
1451 during authorization on the scope.
1452 .It Ft void Fn kauth_deregister_scope "kauth_scope_t scope"
1453 Deregister
1454 .Ar scope
1455 from the scopes available on the system, and free the
1456 .Ft kauth_scope_t
1457 object
1458 .Ar scope .
1459 .El
1460 .Ss Listener Management
1461 Listeners in
1462 .Nm
1463 are authorization callbacks that are called during an authorization
1464 request in the scope which they belong to.
1465 .Pp
1466 When an authorization request is made, all listeners associated with
1467 a scope are called to allow, deny, or defer the request.
1468 .Pp
1469 It is enough for one listener to deny the request in order for the
1470 request to be denied; but all listeners are called during an authorization
1471 process none-the-less.
1472 All listeners are required to allow the request for it to be granted,
1473 and in a case where all listeners defer the request -- leaving the decision
1474 for other listeners -- the request is denied.
1475 .Pp
1476 The following KPI is provided for the management of listeners:
1477 .Bl -tag -width compact
1478 .It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \
1479 "kauth_scope_callback_t cb" "void *cookie"
1480 Create a new listener on the scope with the id
1481 .Ar id ,
1482 setting the default listener to
1483 .Ar cb .
1484 .Ar cookie
1485 is optional user-data that will be passed to the listener when called
1486 during an authorization request.
1487 .It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener"
1488 Removes
1489 .Ar listener
1490 from the scope which it belongs to, ensuring it won't be called again,
1491 and frees the
1492 .Ft kauth_listener_t
1493 object
1494 .Ar listener .
1495 .El
1496 .Pp
1497 .Nm
1498 provides no means for synchronization within listeners.
1499 It is the programmer's responsibility to make sure data used by the
1500 listener is properly locked during its use, as it can be accessed
1501 simultaneously from the same listener called multiple times.
1502 It is also the programmer's responsibility to do garbage collection after
1503 the listener, possibly freeing any allocated data it used.
1504 .Pp
1505 The common method to do the above is by having a reference count to
1506 each listener.
1507 On entry to the listener, this reference count should be raised, and
1508 on exit -- lowered.
1509 .Pp
1510 During the removal of a listener, first
1511 .Fn kauth_scope_unlisten
1512 should be called to make sure the listener code will not be entered in
1513 the future.
1514 Then, the code should wait (possibly sleeping) until the reference count
1515 drops to zero.
1516 When that happens, it is safe to do the final cleanup.
1517 .Pp
1518 Listeners might sleep, so no locks can be held when calling an authorization
1519 wrapper.
1520 .Sh EXAMPLES
1521 Older code had no abstraction of the security model, so most privilege
1522 checks looked like this:
1523 .Bd -literal -offset indent
1524 if (suser(cred, \*[Am]acflag) == 0)
1525 /* allow privileged operation */
1526 .Ed
1527 .Pp
1528 Using the new interface, you must ask for a specific privilege explicitly.
1529 For example, checking whether it is possible to open a socket would look
1530 something like this:
1531 .Bd -literal -offset indent
1532 if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET,
1533 KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM,
1534 IPPROTO_TCP) == 0)
1535 /* allow opening the socket */
1536 .Ed
1537 .Pp
1538 Note that the
1539 .Em securelevel
1540 implications were also integrated into the
1541 .Nm
1542 framework so you don't have to note anything special in the call to the
1543 authorization wrapper, but rather just have to make sure the security
1544 model handles the request as you expect it to.
1545 .Pp
1546 To do that you can just
1547 .Xr grep 1
1548 in the relevant security model directory and have a look at the code.
1549 .Sh EXTENDING KAUTH
1550 Although
1551 .Nm
1552 provides a large set of both detailed and more or less generic requests,
1553 it might be needed eventually to introduce more scopes, actions, or
1554 requests.
1555 .Pp
1556 Adding a new scope should happen only when an entire subsystem is
1557 introduced and it is assumed other parts of the kernel may want to
1558 interfere with its inner-workings.
1559 When a subsystem that has the potential of impacting the security
1560 of the system is introduced, existing security modules must be updated
1561 to also handle actions on the newly added scope.
1562 .Pp
1563 New actions should be added when sets of operations not covered at all
1564 belong in an already existing scope.
1565 .Pp
1566 Requests (or sub-actions) can be added as subsets of existing actions
1567 when an operation that belongs in an already covered area is introduced.
1568 .Pp
1569 Note that all additions should include updates to this manual, the
1570 security models shipped with
1571 .Nx ,
1572 and the example skeleton security model.
1573 .Sh SEE ALSO
1574 .Xr secmodel 9
1575 .Sh HISTORY
1576 The kernel authorization framework first appeared in Mac OS X 10.4.
1577 .Pp
1578 The kernel authorization framework in
1579 .Nx
1580 first appeared in
1581 .Nx 4.0 ,
1582 and is a clean-room implementation based on Apple TN2127, available at
1583 http://developer.apple.com/technotes/tn2005/tn2127.html
1584 .Sh NOTES
1585 As
1586 .Nm
1587 in
1588 .Nx
1589 is still under active development, it is likely that the ABI, and possibly the
1590 API, will differ between
1591 .Nx
1592 versions.
1593 Developers are to take notice of this fact in order to avoid building code
1594 that expects one version of the ABI and running it in a system with a different
1595 one.
1596 .Sh AUTHORS
1597 .An Elad Efrat Aq elad@NetBSD.org
1598 implemented the kernel authorization framework in
1599 .Nx .
1600 .Pp
1601 .An Jason R. Thorpe Aq thorpej@NetBSD.org
1602 provided guidance and answered questions about the Darwin implementation.
1603 .Sh ONE MORE THING
1604 The
1605 .Nm
1606 framework is dedicated to Brian Mitchell, one of the most talented people
1607 I know.
1608 Thanks for everything.