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