1.\" $NetBSD: kauth.9,v 1.35 2006/11/22 12:12:51 elad 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Elad Efrat. 17.\" 4. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd November 22, 2006 32.Dt KAUTH 9 33.Os 34.Sh NAME 35.Nm kauth 36.Nd kernel authorization framework 37.Sh SYNOPSIS 38.In sys/kauth.h 39.Sh DESCRIPTION 40.Nm , 41or kernel authorization, is the subsystem managing all authorization requests 42inside the kernel. 43It manages user credentials and rights, and can be used 44to implement a system-wide security policy. 45It allows external modules to plug-in the authorization process. 46.Pp 47.Nm 48introduces some new concepts, namely 49.Dq scopes 50and 51.Dq listeners , 52which will be detailed together with other useful information for kernel 53developers in this document. 54.Ss Types 55Some 56.Nm 57types include the following: 58.Bl -tag 59.It kauth_cred_t 60Representing credentials that can be associated with an object. 61Includes user- and group-ids (real, effective, and save) as well as group 62membership information. 63.It kauth_scope_t 64Describes a scope. 65.It kauth_listener_t 66Describes a listener. 67.El 68.Ss Terminology 69.Nm 70operates in various 71.Dq scopes , 72each scope holding a group of 73.Dq listeners . 74.Pp 75Each listener works as a callback for when an authorization request within the 76scope is made. 77When such a request is made, all listeners on the scope are passed common 78information such as the credentials of the request context, an identifier for 79the requested operation, and possibly other information as well. 80.Pp 81Every listener examines the passed information and returns its decision 82regarding the requested operation. 83It can either allow, deny, or defer the operation -- in which case, the 84decision is left to the other listeners. 85.Pp 86For an operation to be allowed, all listeners must not return any deny 87or defer decisions. 88.Pp 89Scopes manage listeners that operate in the same aspect of the system. 90.Ss Kernel Programming Interface 91.Nm 92exports a KPI that allows developers both of 93.Nx 94and third-party products to authorize requests, access and modify credentials, 95create and remove scopes and listeners, and perform other miscellaneous operations on 96credentials. 97.Ss Authorization Requests 98.Nm 99provides a single authorization request routine, which all authorization 100requests go through. 101This routine dispatches the request to the listeners of the appropriate scope, 102together with four optional user-data variables, and returns the augmented 103result. 104.Pp 105It is declared as 106.Pp 107.Ft int Fn kauth_authorize_action "kauth_scope_t scope" "kauth_cred_t cred" \ 108"kauth_action_t op" "void *arg0" "void *arg1" "void *arg2" "void *arg3" 109.Pp 110An authorization request can return one of two possible values. 111Zero indicates success -- the operation is allowed; 112.Er EPERM 113(see 114.Xr errno 2 ) 115indicates failure -- the operation is denied. 116.Pp 117Each scope has its own authorization wrapper, to make it easy to call from various 118places by eliminating the need to specify the scope and/or cast values. 119The authorization wrappers are detailed in each scope's section. 120.Ss Generic Scope 121The generic scope, 122.Dq org.netbsd.kauth.generic , 123manages generic authorization requests in the kernel. 124.Pp 125The authorization wrapper for this scope is declared as 126.Pp 127.Ft int Fn kauth_authorize_generic "kauth_cred_t cred" "kauth_action_t op" \ 128"void *arg0" 129.Pp 130The following operations are available for this scope: 131.Bl -tag 132.It Dv KAUTH_GENERIC_ISSUSER 133Checks whether the credentials belong to the super-user. 134.Pp 135Using this request is strongly discouraged and should only be done as a 136temporary place-holder, as it is breaking the separation between the 137interface for authorization requests from the back-end implementation. 138.It Dv KAUTH_GENERIC_CANSEE 139Checks whether an object with one set of credentials can access 140information about another object, possibly with a different set of 141credentials. 142.Pp 143.Ar arg0 144contains the credentials of the object looked at. 145.Pp 146This request should be issued only in cases where generic credentials 147check is required; otherwise it is recommended to use the object-specific 148routines. 149.El 150.Ss System Scope 151The system scope, 152.Dq org.netbsd.kauth.system , 153manages authorization requests affecting the entire system. 154.Pp 155The authorization wrapper for this scope is declared as 156.Pp 157.Ft int Fn kauth_authorize_system "kauth_cred_t cred" \ 158"kauth_action_t op" "enum kauth_system_req req" "void *arg1" "void *arg2" \ 159"void *arg3" 160.Pp 161The following requests are available for this scope: 162.Bl -tag 163.It Dv KAUTH_SYSTEM_ACCOUNTING 164Check if enabling/disabling accounting allowed. 165.It Dv KAUTH_SYSTEM_CHROOT 166.Ar req 167can be any of the following: 168.Bl -tag 169.It Dv KAUTH_REQ_SYSTEM_CHROOT_CHROOT 170Check if calling 171.Xr chroot 2 172is allowed. 173.It Dv KAUTH_REQ_SYSTEM_CHROOT_FCHROOT 174Check if calling 175.Xr fchroot 2 176is allowed. 177.El 178.It Dv KAUTH_SYSTEM_DEBUG 179This request concentrates several debugging-related operations. 180.Ar req 181can be any of the following: 182.Bl -tag 183.It Dv KAUTH_REQ_SYSTEM_DEBUG_IPKDB 184Check if using 185.Xr ipkdb 4 186is allowed. 187.El 188.It Dv KAUTH_SYSTEM_FILEHANDLE 189Check if filehandle operations allowed. 190.It Dv KAUTH_SYSTEM_LKM 191Check if an LKM request is allowed. 192.Pp 193.Ar arg1 194is the command. 195.It Dv KAUTH_SYSTEM_MKNOD 196Check if creating devices is allowed. 197.It Dv KAUTH_SYSTEM_REBOOT 198Check if rebooting is allowed. 199.It Dv KAUTH_SYSTEM_SETIDCORE 200Check if changing coredump settings for set-id processes is allowed. 201.It Dv KAUTH_SYSTEM_SWAPCTL 202Check if privileged 203.Xr swapctl 2 204requests are allowed. 205.It Dv KAUTH_SYSTEM_SYSCTL 206This requests operations related to 207.Xr sysctl 9 . 208.Ar req 209indicates the specific request and can be one of the following: 210.Bl -tag 211.It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD 212Check if adding a 213.Xr sysctl 9 214node is allowed. 215.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE 216Check if deleting a 217.Xr sysctl 9 218node is allowed. 219.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC 220Check if adding description to a 221.Xr sysctl 9 222node is allowed. 223.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT 224Check if accessing private 225.Xr sysctl 9 226nodes is allowed. 227.El 228.It Dv KAUTH_SYSTEM_TIME 229This request groups time-related operations. 230.Ar req 231can be any of the following: 232.Bl -tag 233.It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME 234Check if changing the time using 235.Xr adjtime 2 236is allowed. 237.It Dv KAUTH_REQ_SYSTEM_TIME_BACKWARDS 238Check if setting the time backwards is allowed. 239.It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME 240Check if setting the time using 241.Xr ntp_adjtime 2 242is allowed. 243.It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM 244Check if changing the time (usually via 245.Xr settimeofday 2 ) 246is allowed. 247.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET 248Check if changing the RTC offset is allowed. 249.El 250.El 251.Ss Process Scope 252The process scope, 253.Dq org.netbsd.kauth.process , 254manages authorization requests related to processes in the system. 255.Pp 256The authorization wrapper for this scope is declared as 257.Pp 258.Ft int Fn kauth_authorize_process "kauth_cred_t cred" \ 259"kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \ 260"void *arg3" 261.Pp 262The following operations are available for this scope: 263.Bl -tag 264.It Dv KAUTH_PROCESS_CANSIGNAL 265Checks whether an object with one set of credentials can post signals 266to another process. 267.Pp 268.Ar p 269is the process the signal is being posted to, and 270.Ar arg1 271is the signal number. 272.It Dv KAUTH_PROCESS_CANSEE 273Checks whether an object with one set of credentials can access 274information about another process, possibly with a different set of 275credentials. 276.It Dv KAUTH_PROCESS_CORENAME 277Checks whether the coredump name for the process 278.Ar p 279can be changed. 280.It Dv KAUTH_PROCESS_RESOURCE 281Groups authorization requests related to resource management. 282.Ar arg0 283indicates the sub-action, and can be one of the following: 284.Bl -tag 285.It Dv KAUTH_REQ_PROCESS_RESOURCE_NICE 286Checks whether the 287.Em nice 288value of 289.Ar p 290can be changed to 291.Ar arg2 . 292.It Dv KAUTH_REQ_PROCESS_RESOURCE_RLIMIT 293Checks whether the 294.Em rlimit 295value for 296.Ar arg3 297in 298.Ar p 299can be set to 300.Ar arg2 . 301.El 302.It Dv KAUTH_PROCESS_SETID 303Check if changing the user- or group-ids, groups, or login-name for 304.Ar p 305is allowed. 306.El 307.Ss Network Scope 308The network scope, 309.Dq org.netbsd.kauth.network , 310manages networking-related authorization requests in the kernel. 311.Pp 312The authorization wrapper for this scope is declared as 313.Pp 314.Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \ 315"enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3" 316.Pp 317The following operations are available for this scope: 318.Bl -tag 319.It Dv KAUTH_NETWORK_ALTQ 320Checks if an ALTQ operation is allowed. 321.Pp 322.Ar req 323indicates the ALTQ subsystem in question, and can be one of the following: 324.Pp 325.Bl -tag -compact 326.It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP 327.It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE 328.It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ 329.It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR 330.It Dv KAUTH_REQ_NETWORK_ALTQ_CONF 331.It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ 332.It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC 333.It Dv KAUTH_REQ_NETWORK_ALTQ_JOBS 334.It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ 335.It Dv KAUTH_REQ_NETWORK_ALTQ_RED 336.It Dv KAUTH_REQ_NETWORK_ALTQ_RIO 337.It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ 338.El 339.It Dv KAUTH_NETWORK_BIND 340Checks if a 341.Xr bind 2 342request is allowed. 343.Pp 344.Ar req 345allows to indicate the type of the request to structure listeners and callers 346easier. 347Supported request types: 348.Bl -tag 349.It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT 350Checks if binding to a privileged/reserved port is allowed. 351.El 352.It Dv KAUTH_NETWORK_FIREWALL 353Checks if firewall-related operations are allowed. 354.Pp 355.Ar req 356indicates the sub-action, and can be one of the following: 357.Bl -tag 358.It Dv KAUTH_REQ_NETWORK_FIREWALL_FW 359Modification of packet filtering rules. 360.It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT 361Modification of NAT rules. 362.El 363.It Dv KAUTH_NETWORK_INTERFACE 364Checks if network interface-related operations are allowed. 365.Pp 366.Ar arg1 367is (optionally) the 368.Ft struct ifnet * 369associated with the interface. 370.Ar arg2 371is (optionally) an 372.Ft int 373describing the interface-specific operation. 374.Ar arg3 375is (optionally) a pointer to the interface-specific request structure. 376.Ar req 377indicates the sub-action, and can be one of the following: 378.Bl -tag 379.It Dv KAUTH_REQ_NETWORK_INTERFACE_GET 380Check if retrieving information from the device is allowed. 381.It Dv KAUTH_REQ_NETWORK_INTERFACE_GETPRIV 382Check if retrieving privileged information from the device is allowed. 383.It Dv KAUTH_REQ_NETWORK_INTERFACE_SET 384Check if setting parameters on the device is allowed. 385.It Dv KAUTH_REQ_NETWORK_INTERFACE_SETPRIV 386Check if setting privileged parameters on the device is allowed. 387.El 388.Pp 389Note that unless the 390.Ft struct ifnet * 391for the interface was passed in 392.Ar arg1 , 393there's no way to tell what structure 394.Ar arg3 395is. 396.It Dv KAUTH_NETWORK_FORWSRCRT 397Checks whether status of forwarding of source-routed packets can be modified 398or not. 399.It Dv KAUTH_NETWORK_ROUTE 400Checks if a routing-related request is allowed. 401.Pp 402.Ar arg1 403is the 404.Ft struct rt_msghdr * 405for the request. 406.It Dv KAUTH_NETWORK_SOCKET 407Checks if a socket related operation is allowed. 408.Pp 409.Ar req 410allows to indicate the type of the request to structure listeners and callers 411easier. 412Supported request types: 413.Bl -tag 414.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK 415Checks if opening a raw socket is allowed. 416.It Dv KAUTH_REQ_NETWORK_SOCKET_OPEN 417Checks if opening a socket is allowed. 418.Ar arg1 , arg2 , 419and 420.Ar arg3 421are all 422.Ft int 423parameters describing the domain, socket type, and protocol, 424respectively. 425.It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE 426Checks if looking at the socket passed is allowed. 427.Pp 428.Ar arg1 429is a 430.Ft struct socket * 431describing the socket. 432.El 433.El 434.Ss Machine-dependent Scope 435The machine-dependent (machdep) scope, 436.Dq org.netbsd.kauth.machdep , 437manages machine-dependent authorization requests in the kernel. 438.Pp 439The authorization wrapper for this scope is declared as 440.Pp 441.Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \ 442"enum kauth_machdep_req req" "void *arg1" "void *arg2" "void *arg3" 443.Pp 444In this scope, 445.Ar req 446always indicates the machine for the request. 447Below is the list of available request hierarchy. 448.Bl -tag 449.It Dv KAUTH_MACHDEP_ALPHA 450The request is alpha specific. 451.Pp 452Available requests as 453.Ar req 454are: 455.Bl -tag 456.It Dv KAUTH_REQ_MACHDEP_ALPHA_UNMANAGEDMEM 457Access to unmanaged memory requested. 458.El 459.It Dv KAUTH_MACHDEP_X86 460The request is x86 specific. 461.Pp 462Available requests as 463.Ar req 464are: 465.Bl -tag 466.It Dv KAUTH_REQ_MACHDEP_X86_IOPL 467Checks if IOPL is allowed to be modified. 468.It Dv KAUTH_REQ_MACHDEP_X86_IOPERM 469Checks if IOPERM is allowed to be modified. 470.It Dv KAUTH_REQ_MACHDEP_X86_MTRR_SET 471Checks if the MTRR can be set. 472.It Dv KAUTH_REQ_MACHDEP_X86_UNMANAGEDMEM 473Access to unmanaged memory requested. 474.El 475.It Dv KAUTH_MACHDEP_X86_64 476The request is x86-64 specific. 477.Pp 478Available requests as 479.Ar arg1 480are: 481.Bl -tag 482.It Dv KAUTH_REQ_MACHDEP_X86_64_MTRR_GET 483Check if MTRR values can be retrieved. 484.El 485.El 486.Ss Device Scope 487The device scope, 488.Dq org.netbsd.kauth.device , 489manages authorization requests related to devices on the system. 490Devices can be, for example, terminals, tape drives, and any other hardware. 491Network devices specifically are handled by the 492.Em network 493scope. 494.Pp 495In addition to the standard authorization wrapper: 496.Pp 497.Ft int Fn kauth_authorize_device "kauth_cred_t cred" "kauth_action_t op" \ 498"void *arg0" "void *arg1" "void *arg2" "void *arg3" 499.Pp 500this scope provides authorization wrappers for various device types. 501.Pp 502.Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \ 503"struct tty *tty" 504.Pp 505Authorizes requests for 506.Em terminal devices 507on the system. 508The third argument, 509.Ar tty , 510is the terminal device in question. 511It is passed to the listener as 512.Ar arg0 . 513The second argument, 514.Ar op , 515is the action and can be one of the following: 516.Bl -tag 517.It Dv KAUTH_DEVICE_TTY_OPEN 518Open the terminal device pointed to by 519.Ar tty . 520.It Dv KAUTH_DEVICE_TTY_PRIVSET 521Set privileged settings on the terminal device pointed to by 522.Ar tty . 523.El 524.Pp 525.Ft int Fn kauth_authorize_device_spec "kauth_cred_t cred" \ 526"enum kauth_device_req req" "struct vnode *vp" 527.Pp 528Authorizes requests for 529.Em special files , 530usually disk devices, but also direct memory access, on the system. 531.Pp 532It passes 533.Dq KAUTH_DEVICE_RAWIO_SPEC 534as the action to the listener, and accepts two arguments. 535.Ar req , 536passed to the listener as 537.Ar arg0 , 538is access requested, and can be one of 539.Dq KAUTH_REQ_DEVICE_RAWIO_SPEC_READ , 540.Dq KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE , 541or 542.Dq KAUTH_REQ_DEVICE_RAWIO_SPEC_RW , 543representing read, write, or both read/write access respectively. 544.Ar vp 545is the vnode of the special file in question, and is passed to the listener as 546.Ar arg1 . 547.Pp 548Keep in mind that it is the responsibility of the security model developer to 549check whether the underlying device is a disk or the system memory, using 550.Fn iskmemdev : 551.Bd -literal -offset indent 552if ((vp-\*[Gt]v_type == VCHR) \*[Am]\*[Am] 553 iskmemdev(vp-\*[Gt]v_un.vu_specinfo-\*[Gt]si_rdev)) 554 /* system memory access */ 555.Ed 556.Pp 557.Ft int Fn kauth_authorize_device_passthru "kauth_cred_t cred" "dev_t dev" \ 558"void *data" 559.Pp 560Authorizes hardware 561.Em passthru 562requests, or user commands passed directly to the hardware. 563These have the potential of resulting in direct disk and/or memory access. 564.Pp 565It passes 566.Dq KAUTH_DEVICE_RAWIO_PASSTHRU 567as the action to the listener, and accepts two arguments. 568.Ar dev , 569passed as 570.Ar arg1 571to the listener, is the device for which the request is made, and 572.Ar data , 573passed as 574.Ar arg2 575to the listener, is device-specific data that may be associated with the 576request. 577.Ss Credentials Accessors and Mutators 578.Nm 579has a variety of accessor and mutator routines to handle 580.Ft kauth_cred_t 581objects. 582.Pp 583The following routines can be used to access and modify the user- and 584group-ids in a 585.Ft kauth_cred_t : 586.Bl -tag 587.It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred" 588Returns the real user-id from 589.Ar cred . 590.It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred" 591Returns the effective user-id from 592.Ar cred . 593.It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred" 594Returns the saved user-id from 595.Ar cred . 596.It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid" 597Sets the real user-id in 598.Ar cred 599to 600.Ar uid . 601.It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid" 602Sets the effective user-id in 603.Ar cred 604to 605.Ar uid . 606.It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid" 607Sets the saved user-id in 608.Ar cred 609to 610.Ar uid . 611.It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred" 612Returns the real group-id from 613.Ar cred . 614.It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred" 615Returns the effective group-id from 616.Ar cred . 617.It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred" 618Returns the saved group-id from 619.Ar cred . 620.It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid" 621Sets the real group-id in 622.Ar cred 623to 624.Ar gid . 625.It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid" 626Sets the effective group-id in 627.Ar cred 628to 629.Ar gid . 630.It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid" 631Sets the saved group-id in 632.Ar cred 633to 634.Ar gid . 635.It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred" 636Return the reference count for 637.Ar cred . 638.El 639.Pp 640The following routines can be used to access and modify the group 641list in a 642.Ft kauth_cred_t : 643.Bl -tag 644.It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \ 645"int *resultp" 646Checks if the group-id 647.Ar gid 648is a member in the group list of 649.Ar cred . 650.Pp 651If it is, 652.Ar resultp 653will be set to one, otherwise, to zero. 654.Pp 655The return value is an error code, or zero for success. 656.It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred" 657Return the number of groups in the group list of 658.Ar cred . 659.It Ft int Fn kauth_cred_group "kauth_cred_t cred" "u_int idx" 660Return the group-id of the group at index 661.Ar idx 662in the group list of 663.Ar cred . 664.It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "gid_t *groups" \ 665"size_t ngroups" "uid_t gmuid" 666Copy 667.Ar ngroups 668groups from array pointed to by 669.Ar groups 670to the group list in 671.Ar cred , 672adjusting the number of groups in 673.Ar cred 674appropriately. 675.Pp 676Any groups remaining will be set to an invalid value. 677.Pp 678.Ar gmuid 679is unused for now, and to maintain interface compatibility with the Darwin 680KPI. 681.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \ 682"size_t ngroups" 683Copy 684.Ar ngroups 685groups from the group list in 686.Ar cred 687to the buffer pointed to by 688.Ar groups . 689.Pp 690The number of groups in 691.Ar cred 692will be returned. 693.El 694.Ss Credentials Inheritance and Reference Counting 695.Nm 696provides a KPI for handling a 697.Ft kauth_cred_t 698in shared credentials situations and credential inheritance. 699.Pp 700When a 701.Ft kauth_cred_t 702is first allocated, its reference count is set to 1. 703However, with time, its reference count can grow as more objects (processes, 704LWPs, files, etc.) reference it. 705One such case is during a 706.Xr fork 2 707where the child process and its LWPs inherit the credentials of the parent. 708.Pp 709To prevent freeing a 710.Ft kauth_cred_t 711while it is still referenced, the following routines are available to maintain 712its reference count: 713.Bl -tag 714.It Ft void Fn kauth_cred_hold "kauth_cred_t cred" 715Increases reference count to 716.Ar cred 717by one. 718.It Ft void Fn kauth_cred_free "kauth_cred_t cred" 719Decreases the reference count to 720.Ar cred 721by one. 722.Pp 723If the reference count dropped to zero, the memory used by 724.Ar cred 725will be returned back to the memory pool. 726.El 727.Ss Credentials Memory Management 728Data-structures for credentials, listeners, and scopes are allocated from 729memory pools managed by the 730.Xr pool 9 731subsystem. 732.Pp 733The 734.Ft kauth_cred_t 735objects have their own memory management routines: 736.Bl -tag 737.It Ft kauth_cred_t Fn kauth_cred_alloc "void" 738Allocates a new 739.Ft kauth_cred_t , 740initializes its lock, and sets its reference count to one. 741.El 742.Ss Conversion Routines 743Sometimes it might be necessary to convert a 744.Ft kauth_cred_t 745to userland's view of credentials, a 746.Ft struct uucred , 747or vice versa. 748.Pp 749The following routines are available for these cases: 750.Bl -tag 751.It Ft void Fn kauth_uucred_to_cred "kauth_cred_t cred" "const struct uucred *uucred" 752Convert userland's view of credentials to a 753.Ft kauth_cred_t . 754.Pp 755This includes effective user- and group-ids, a number of groups, and a group 756list. 757The reference count is set to one. 758.Pp 759Note that 760.Nm 761will try to copy as many groups as can be held inside a 762.Ft kauth_cred_t . 763.It Ft void Fn kauth_cred_to_uucred "struct uucred *uucred" "const kauth_cred_t cred" 764Convert 765.Ft kauth_cred_t 766to userland's view of credentials. 767.Pp 768This includes effective user- and group-ids, a number of groups, and a group 769list. 770.Pp 771Note that 772.Nm 773will try to copy as many groups as can be held inside a 774.Ft struct uucred . 775.It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred" 776Compares 777.Ar cred 778with the userland credentials in 779.Ar uucred . 780.Pp 781Common values that will be compared are effective user- and group-ids, and 782the group list. 783.El 784.Ss Miscellaneous Routines 785Other routines provided by 786.Nm 787are: 788.Bl -tag 789.It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2" 790Clone credentials from 791.Ar cred1 792to 793.Ar cred2 , 794except for the lock and reference count. 795.Pp 796.It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred" 797Duplicate 798.Ar cred . 799.Pp 800What this routine does is call 801.Fn kauth_cred_alloc 802followed by a call to 803.Fn kauth_cred_clone . 804.It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred" 805Works like 806.Fn kauth_cred_dup , 807except for a few differences. 808.Pp 809If 810.Ar cred 811already has a reference count of one, it will be returned. 812Otherwise, a new 813.Ft kauth_cred_t 814will be allocated and the credentials from 815.Ar cred 816will be cloned to it. 817Last, a call to 818.Fn kauth_cred_free 819for 820.Ar cred 821will be done. 822.It Ft kauth_cred_t Fn kauth_cred_get "void" 823Return the credentials associated with the current LWP. 824.El 825.Ss Scope Management 826.Nm 827provides routines to manage the creation and deletion of scopes on the 828system. 829.Pp 830Note that the built-in scopes, the 831.Dq generic 832scope and the 833.Dq process 834scope, can't be deleted. 835.Bl -tag 836.It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \ 837"kauth_scope_callback_t cb" "void *cookie" 838Register a new scope on the system. 839.Ar id 840is the name of the scope, usually in reverse DNS-like notation. 841For example, 842.Dq org.netbsd.kauth.myscope . 843.Ar cb 844is the default listener, to which authorization requests for this scope 845will be dispatched to. 846.Ar cookie 847is optional user-data that will be passed to all listeners 848during authorization on the scope. 849.It Ft void Fn kauth_deregister_scope "kauth_scope_t scope" 850Deregister 851.Ar scope 852from the scopes available on the system. 853.El 854.Ss Listener Management 855Listeners in 856.Nm 857are authorization callbacks that are called during an authorization 858request in the scope which they belong to. 859.Pp 860When an authorization request is made, all listeners associated with 861a scope are called to allow, deny, or defer the request. 862.Pp 863It is enough for one listener to deny the request in order for the 864request to be denied; but all listeners are called during an authorization 865process none-the-less. 866All listeners are required to allow the request for it to be granted, 867and in a case where all listeners defer the request -- leaving the decision 868for other listeners -- the request is denied. 869.Pp 870The following KPI is provided for the management of listeners: 871.Bl -tag 872.It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \ 873"kauth_scope_callback_t cb" "void *cookie" 874Create a new listener on the scope with the id 875.Ar id , 876setting the default listener to 877.Ar cb . 878.\".Ar cookie 879.\"is optional user-data that will be passed to the listener when called 880.\"during an authorization request. 881.It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener" 882Remove 883.Ar listener 884from the scope which it belongs to. 885.Pp 886Effectively what this does is is remove the callback from the chain of 887functions to be called when an authorization request is made, preventing 888from the listener from being entered in the future. 889.El 890.Pp 891.Nm 892provides no means for synchronization within listeners. 893It is the the programmer's responsibility to make sure data used by the 894listener is properly locked during its use, as it can be accessed 895simultaneously from the same listener called multiple times. 896It is also the programmer's responsibility to do garbage collection after 897the listener, possibly freeing any allocated data it used. 898.Pp 899The common method to do the above is by having a reference count to 900each listener. 901On entry to the listener, this reference count should be raised, and 902on exit -- lowered. 903.Pp 904During the removal of a listener, first 905.Fn kauth_scope_unlisten 906should be called to make sure the listener code will not be entered in 907the future. 908Then, the code should wait (possibly sleeping) until the reference count 909drops to zero. 910When that happens, it is safe to do the final cleanup. 911.Pp 912Listeners might sleep, so no locks can be held when calling an authorization 913wrapper. 914.Sh EXAMPLES 915Older code had no abstraction of the security model, so most privilege 916checks looked like this: 917.Bd -literal -offset indent 918if (suser(cred, \*[Am]acflag) == 0) 919 /* allow privileged operation */ 920.Ed 921.Pp 922Using the new interface, you must ask for a specific privilege explicitly. 923For example, checking whether it is possible to open a socket would look 924something like this: 925.Bd -literal -offset indent 926if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET, 927 KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM, 928 IPPROTO_TCP) == 0) 929 /* allow opening the socket */ 930.Ed 931.Pp 932Note that the 933.Em securelevel 934implications were also integrated into the 935.Nm 936framework so you don't have to note anything special in the call to the 937authorization wrapper, but rather just have to make sure the security 938model handles the request as you expect it to. 939.Pp 940To do that you can just 941.Xr grep 1 942in the relevant security model directory and have a look at the code. 943.Sh EXTENDING KAUTH 944Although 945.Nm 946provides a large set of both detailed and more or less generic requests, 947it might be needed eventually to introduce more scopes, actions, or 948requests. 949.Pp 950Adding a new scope should happen only when an entire subsystem is 951introduced and it is assumed other parts of the kernel may want to 952interfere with its inner-workings. 953When a subsystem that has the potential of impacting the security 954if the system is introduced, existing security modules must be updated 955to also handle actions on the newly added scope. 956.Pp 957New actions should be added when sets of operations not covered at all 958belong in an already existing scope. 959.Pp 960Requests (or sub-actions) can be added as subsets of existing actions 961when an operation that belongs in an already covered area is introduced. 962.Pp 963Note that all additions should include updates to this manual, the 964security models shipped with 965.Nx , 966and the example skeleton security model. 967.Sh SEE ALSO 968.Xr secmodel 9 969.Sh HISTORY 970The kernel authorization framework first appeared in Mac OS X 10.4. 971.Pp 972The kernel authorization framework in 973.Nx 974first appeared in 975.Nx 4.0 , 976and is a clean-room implementation based on Apple TN2127, available at 977http://developer.apple.com/technotes/tn2005/tn2127.html 978.Sh AUTHORS 979.An Elad Efrat Aq elad@NetBSD.org 980implemented the kernel authorization framework in 981.Nx . 982.Pp 983.An Jason R. Thorpe Aq thorpej@NetBSD.org 984provided guidance and answered questions about the Darwin implementation. 985.Sh ONE MORE THING 986The 987.Nm 988framework is dedicated to Brian Mitchell, one of the most talented people 989I know. 990Thanks for everything. 991