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