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