1.\" $NetBSD: kauth.9,v 1.20 2006/10/13 15:39:18 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 October 13, 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_RAWIO 198This request groups raw access to system resources. 199.Pp 200.Ar req 201indicates what is the underlying resource being access, and can be one of the 202following: 203.Bl -tag 204.It Dv KAUTH_REQ_SYSTEM_RAWIO_DISK 205The underlying resource is a disk. 206.It Dv KAUTH_REQ_SYSTEM_RAWIO_MEMORY 207The underlying resource is the machine memory. 208.El 209.Pp 210.Ar arg1 211indicates the access requested, and can be one of the following: 212.Bl -tag 213.It Dv KAUTH_REQ_SYSTEM_RAWIO_READ 214Read access is requested. 215.It Dv KAUTH_REQ_SYSTEM_RAWIO_RW 216Both read and write access are requested. 217.It Dv KAUTH_REQ_SYSTEM_RAWIO_WRITE 218Write access is requested. 219.El 220.Pp 221If the request is for a disk device, 222.Ar arg2 223should contain a 224.Ft struct vnode * 225for the vnode in question, and 226.Ar arg3 227should contain the device number. 228.Pp 229The behavior if any of the above is not provided is policy-dependent. 230.It Dv KAUTH_SYSTEM_REBOOT 231Check if rebooting is allowed. 232.It Dv KAUTH_SYSTEM_SETIDCORE 233Check if changing coredump settings for set-id processes is allowed. 234.It Dv KAUTH_SYSTEM_SWAPCTL 235Check if privileged 236.Xr swapctl 2 237requests are allowed. 238.It Dv KAUTH_SYSTEM_SYSCTL 239This requests operations related to 240.Xr sysctl 9 . 241.Ar req 242indicates the specific request and can be one of the following: 243.Bl -tag 244.It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD 245Check if adding a 246.Xr sysctl 9 247node is allowed. 248.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE 249Check if deleting a 250.Xr sysctl 9 251node is allowed. 252.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC 253Check if adding description to a 254.Xr sysctl 9 255node is allowed. 256.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT 257Check if accessing private 258.Xr sysctl 9 259nodes is allowed. 260.El 261.It Dv KAUTH_SYSTEM_TIME 262This request groups time-related operations. 263.Ar req 264can be any of the following: 265.Bl -tag 266.It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME 267Check if changing the time using 268.Xr adjtime 2 269is allowed. 270.It Dv KAUTH_REQ_SYSTEM_TIME_BACKWARDS 271Check if setting the time backwards is allowed. 272.It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME 273Check if setting the time using 274.Xr ntp_adjtime 2 275is allowed. 276.It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM 277Check if changing the time (usually via 278.Xr settimeofday 2 ) 279is allowed. 280.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET 281Check if changing the RTC offset is allowed. 282.El 283.El 284.Ss Process Scope 285The process scope, 286.Dq org.netbsd.kauth.process , 287manages authorization requests related to processes in the system. 288.Pp 289The authorization wrapper for this scope is declared as 290.Pp 291.Ft int Fn kauth_authorize_process "kauth_cred_t cred" \ 292"kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \ 293"void *arg3" 294.Pp 295The following operations are available for this scope: 296.Bl -tag 297.It Dv KAUTH_PROCESS_CANSIGNAL 298Checks whether an object with one set of credentials can post signals 299to another process. 300.Pp 301.Ar arg1 302and 303.Ar arg2 304contain the credentials 305.Ft ( kauth_cred_t ) 306and the process data 307.Ft ( struct proc * ) 308of the process the signal is posted to, respectively. 309.Ar arg3 310is the signal to be posted. 311.It Dv KAUTH_PROCESS_CANSEE 312Checks whether an object with one set of credentials can access 313information about another process, possibly with a different set of 314credentials. 315.It Dv KAUTH_PROCESS_CORENAME 316Checks whether the coredump name for the process 317.Ar p 318can be changed. 319.It Dv KAUTH_PROCESS_RESOURCE 320Groups authorization requests related to resource management. 321.Ar arg0 322indicates the sub-action, and can be one of the following: 323.Bl -tag 324.It Dv KAUTH_REQ_PROCESS_RESOURCE_NICE 325Checks whether the 326.Em nice 327value of 328.Ar p 329can be changed to 330.Ar arg2 . 331.It Dv KAUTH_REQ_PROCESS_RESOURCE_RLIMIT 332Checks whether the 333.Em rlimit 334value for 335.Ar arg3 336in 337.Ar p 338can be set to 339.Ar arg2 . 340.El 341.It Dv KAUTH_PROCESS_SETID 342Check if changing the user- or group-ids, groups, or login-name for 343.Ar p 344is allowed. 345.El 346.Ss Network Scope 347The network scope, 348.Dq org.netbsd.kauth.network , 349manages networking-related authorization requests in the kernel. 350.Pp 351The authorization wrapper for this scope is declared as 352.Pp 353.Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \ 354"enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3" 355.Pp 356The following operations are available for this scope: 357.Bl -tag 358.It Dv KAUTH_NETWORK_ALTQ 359Checks if an ALTQ operation is allowed. 360.Pp 361.Ar req 362indicates the ALTQ subsystem in question, and can be one of the following: 363.Pp 364.Bl -tag -compact 365.It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP 366.It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE 367.It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ 368.It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR 369.It Dv KAUTH_REQ_NETWORK_ALTQ_CONF 370.It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ 371.It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC 372.It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ 373.It Dv KAUTH_REQ_NETWORK_ALTQ_RED 374.It Dv KAUTH_REQ_NETWORK_ALTQ_RIO 375.It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ 376.El 377.It Dv KAUTH_NETWORK_BIND 378Checks if a 379.Xr bind 2 380request is allowed. 381.Pp 382.Ar req 383allows to indicate the type of the request to structure listeners and callers 384easier. 385Supported request types: 386.Bl -tag 387.It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT 388Checks if binding to a privileged/reserved port is allowed. 389.El 390.It Dv KAUTH_NETWORK_FIREWALL 391Checks if firewall-related operations are allowed. 392.Pp 393.Ar req 394indicates the sub-action, and can be one of the following: 395.Bl -tag 396.It Dv KAUTH_REQ_NETWORK_FIREWALL_FW 397Modification of packet filtering rules. 398.It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT 399Modification of NAT rules. 400.El 401.It Dv KAUTH_NETWORK_FORWSRCRT 402Checks whether status of forwarding of source-routed packets can be modified 403or not. 404.It Dv KAUTH_NETWORK_ROUTE 405Checks if a routing-related request is allowed. 406.Pp 407.Ar arg1 408is the 409.Ft struct rt_msghdr * 410for the request. 411.It Dv KAUTH_NETWORK_SOCKET 412Checks if a 413.Xr socket 2 414request is allowed. 415.Pp 416.Ar req 417allows to indicate the type of the request to structure listeners and callers 418easier. 419Supported request types: 420.Bl -tag 421.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK 422Checks if opening a raw socket is allowed. 423.It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE 424Checks if looking at the socket passed is allowed. 425.Pp 426.Ar arg1 427is a 428.Ft struct socket * 429describing the socket. 430.El 431.El 432.Ss Machine-dependent Scope 433The machine-dependent (machdep) scope, 434.Dq org.netbsd.kauth.machdep , 435manages machine-dependent authorization requests in the kernel. 436.Pp 437The authorization wrapper for this scope is declared as 438.Pp 439.Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \ 440"enum kauth_machdep_req req" "void *arg1" "void *arg2" "void *arg3" 441.Pp 442In this scope, 443.Ar req 444always indicates the machine for the request. 445Below is the list of available request hierarchy. 446.Bl -tag 447.It Dv KAUTH_MACHDEP_X86 448The request is x86 specific. 449.Pp 450Available requests as 451.Ar arg1 452are: 453.Bl -tag 454.It Dv KAUTH_REQ_MACHDEP_X86_IOPL 455Checks if IOPL is allowed to be modified. 456.It Dv KAUTH_REQ_MACHDEP_X86_IOPERM 457Checks if IOPERM is allowed to be modified. 458.It Dv KAUTH_REQ_MACHDEP_X86_MTRR_SET 459Checks if the MTRR can be set. 460.El 461.It Dv KAUTH_MACHDEP_X86_64 462The request is x86-64 specific. 463.Pp 464Available requests as 465.Ar arg1 466are: 467.Bl -tag 468.It Dv KAUTH_REQ_MACHDEP_X86_64_MTRR_GET 469Check if MTRR values can be retrieved. 470.El 471.El 472.Ss Device Scope 473The device scope, 474.Dq org.netbsd.kauth.device , 475manages authorization requests related to devices on the system. 476Devices can be, for example, terminals, tape drives, and any other hardware. 477Network devices specifically are handled by the 478.Em network 479scope. 480.Pp 481This scope has an authorization routine per device class on the system. 482.Pp 483.Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \ 484"struct tty *tty" 485.Pp 486Authorizes requests for 487.Em terminal devices 488on the system. 489The third argument, 490.Ar tty , 491is the terminal device in question. 492The second argument is one of the following: 493.Bl -tag 494.It Dv KAUTH_DEVICE_TTY_OPEN 495Open the terminal device pointed to by 496.Ar tty . 497.It Dv KAUTH_DEVICE_TTY_PRIVSET 498Set privileged settings on the terminal device pointed to by 499.Ar tty . 500.El 501.Ss Credentials Accessors and Mutators 502.Nm 503has a variety of accessor and mutator routines to handle 504.Ft kauth_cred_t 505objects. 506.Pp 507The following routines can be used to access and modify the user- and 508group-ids in a 509.Ft kauth_cred_t : 510.Bl -tag 511.It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred" 512Returns the real user-id from 513.Ar cred . 514.It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred" 515Returns the effective user-id from 516.Ar cred . 517.It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred" 518Returns the saved user-id from 519.Ar cred . 520.It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid" 521Sets the real user-id in 522.Ar cred 523to 524.Ar uid . 525.It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid" 526Sets the effective user-id in 527.Ar cred 528to 529.Ar uid . 530.It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid" 531Sets the saved user-id in 532.Ar cred 533to 534.Ar uid . 535.It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred" 536Returns the real group-id from 537.Ar cred . 538.It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred" 539Returns the effective group-id from 540.Ar cred . 541.It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred" 542Returns the saved group-id from 543.Ar cred . 544.It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid" 545Sets the real group-id in 546.Ar cred 547to 548.Ar gid . 549.It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid" 550Sets the effective group-id in 551.Ar cred 552to 553.Ar gid . 554.It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid" 555Sets the saved group-id in 556.Ar cred 557to 558.Ar gid . 559.It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred" 560Return the reference count for 561.Ar cred . 562.El 563.Pp 564The following routines can be used to access and modify the group 565list in a 566.Ft kauth_cred_t : 567.Bl -tag 568.It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \ 569"int *resultp" 570Checks if the group-id 571.Ar gid 572is a member in the group list of 573.Ar cred . 574.Pp 575If it is, 576.Ar resultp 577will be set to one, otherwise, to zero. 578.Pp 579The return value is an error code, or zero for success. 580.It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred" 581Return the number of groups in the group list of 582.Ar cred . 583.It Ft int Fn kauth_cred_group "kauth_cred_t cred" "u_int idx" 584Return the group-id of the group at index 585.Ar idx 586in the group list of 587.Ar cred . 588.It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "gid_t *groups" \ 589"size_t ngroups" "uid_t gmuid" 590Copy 591.Ar ngroups 592groups from array pointed to by 593.Ar groups 594to the group list in 595.Ar cred , 596adjusting the number of groups in 597.Ar cred 598appropriately. 599.Pp 600Any groups remaining will be set to an invalid value. 601.Pp 602.Ar gmuid 603is unused for now, and to maintain interface compatibility with the Darwin 604KPI. 605.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \ 606"size_t ngroups" 607Copy 608.Ar ngroups 609groups from the group list in 610.Ar cred 611to the buffer pointed to by 612.Ar groups . 613.Pp 614The number of groups in 615.Ar cred 616will be returned. 617.El 618.Ss Credentials Inheritance and Reference Counting 619.Nm 620provides a KPI for handling a 621.Ft kauth_cred_t 622in shared credentials situations and credential inheritance. 623.Pp 624When a 625.Ft kauth_cred_t 626is first allocated, its reference count is set to 1. 627However, with time, its reference count can grow as more objects (processes, 628LWPs, files, etc.) reference it. 629One such case is during a 630.Xr fork 2 631where the child process and its LWPs inherit the credentials of the parent. 632.Pp 633To prevent freeing a 634.Ft kauth_cred_t 635while it is still referenced, the following routines are available to maintain 636its reference count: 637.Bl -tag 638.It Ft void Fn kauth_cred_hold "kauth_cred_t cred" 639Increases reference count to 640.Ar cred 641by one. 642.It Ft void Fn kauth_cred_free "kauth_cred_t cred" 643Decreases the reference count to 644.Ar cred 645by one. 646.Pp 647If the reference count dropped to zero, the memory used by 648.Ar cred 649will be returned back to the memory pool. 650.El 651.Ss Credentials Memory Management 652Data-structures for credentials, listeners, and scopes are allocated from 653memory pools managed by the 654.Xr pool 9 655subsystem. 656.Pp 657The 658.Ft kauth_cred_t 659objects have their own memory management routines: 660.Bl -tag 661.It Ft kauth_cred_t Fn kauth_cred_alloc "void" 662Allocates a new 663.Ft kauth_cred_t , 664initializes its lock, and sets its reference count to one. 665.El 666.Ss Conversion Routines 667Sometimes it might be necessary to convert a 668.Ft kauth_cred_t 669to a predecessing type, such as 670.Ft struct pcred 671or 672.Ft struct ucred , 673or convert credentials passed from userland as a 674.Ft struct uucred 675to a 676.Ft kauth_cred_t . 677.Pp 678The following routines are available for these cases: 679.Bl -tag 680.It Ft void Fn kauth_cred_topcred "kauth_cred_t cred" "struct pcred *pcred" 681Convert a 682.Ft kauth_cred_t 683to a 684.Ft struct pcred . 685.Pp 686This includes real and saved user- and group-ids and reference count, copied 687from 688.Ar cred . 689The 690.Ar pc_ucred 691field in the destination is set to 692.Dv NULL . 693.It Ft void Fn kauth_cred_toucred "kauth_cred_t cred" "struct ucred *ucred" 694Convert a 695.Ft kauth_cred_t 696to a 697.Ft struct ucred . 698.Pp 699This includes effective user- and group-ids, number of groups, and the group 700list from 701.Ar cred . 702.Pp 703Note that 704.Nm 705will try to copy as many groups as 706.Ar ucred 707can hold. 708.It Ft void Fn kauth_cred_uucvt "kauth_cred_t cred" "const struct uucred *uucred" 709Convert userland's view of credentials to a 710.Ft kauth_cred_t . 711.Pp 712This includes effective user- and group-ids, a number of groups, and a group 713list. 714The reference count is set to one. 715.Pp 716Note that 717.Nm 718will try to copy as many groups as can be held inside a 719.Ft kauth_cred_t . 720The addition of groups will also guarantee order and no duplicates. 721.It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred" 722Compares 723.Ar cred 724with the userland credentials in 725.Ar uucred . 726.Pp 727Common values that will be compared are effective user- and group-ids, and 728the group list. 729.El 730.Ss Miscellaneous Routines 731Other routines provided by 732.Nm 733are: 734.Bl -tag 735.It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2" 736Clone credentials from 737.Ar cred1 738to 739.Ar cred2 , 740except for the lock and reference count. 741.Pp 742.It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred" 743Duplicate 744.Ar cred . 745.Pp 746What this routine does is call 747.Fn kauth_cred_alloc 748followed by a call to 749.Fn kauth_cred_clone . 750.It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred" 751Works like 752.Fn kauth_cred_dup , 753except for a few differences. 754.Pp 755If 756.Ar cred 757already has a reference count of one, it will be returned. 758Otherwise, a new 759.Ft kauth_cred_t 760will be allocated and the credentials from 761.Ar cred 762will be cloned to it. 763Last, a call to 764.Fn kauth_cred_free 765for 766.Ar cred 767will be done. 768.It Ft kauth_cred_t Fn kauth_cred_get "void" 769Return the credentials associated with the current LWP. 770.El 771.Ss Scope Management 772.Nm 773provides routines to manage the creation and deletion of scopes on the 774system. 775.Pp 776Note that the built-in scopes, the 777.Dq generic 778scope and the 779.Dq process 780scope, can't be deleted. 781.Bl -tag 782.It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \ 783"kauth_scope_callback_t cb" "void *cookie" 784Register a new scope on the system. 785.Ar id 786is the name of the scope, usually in reverse DNS-like notation. 787For example, 788.Dq org.netbsd.kauth.myscope . 789.Ar cb 790is the default listener, to which authorization requests for this scope 791will be dispatched to. 792.Ar cookie 793is optional user-data that will be passed to all listeners 794during authorization on the scope. 795.It Ft void Fn kauth_deregister_scope "kauth_scope_t scope" 796Deregister 797.Ar scope 798from the scopes available on the system. 799.El 800.Ss Listener Management 801Listeners in 802.Nm 803are authorization callbacks that are called during an authorization 804request in the scope which they belong to. 805.Pp 806When an authorization request is made, all listeners associated with 807a scope are called to allow, deny, or defer the request. 808.Pp 809It is enough for one listener to deny the request in order for the 810request to be denied; but all listeners are called during an authorization 811process none-the-less. 812All listeners are required to allow the request for it to be granted, 813and in a case where all listeners defer the request -- leaving the decision 814for other listeners -- the request is denied. 815.Pp 816The following KPI is provided for the management of listeners: 817.Bl -tag 818.It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \ 819"kauth_scope_callback_t cb" "void *cookie" 820Create a new listener on the scope with the id 821.Ar id , 822setting the default listener to 823.Ar cb . 824.\".Ar cookie 825.\"is optional user-data that will be passed to the listener when called 826.\"during an authorization request. 827.It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener" 828Remove 829.Ar listener 830from the scope which it belongs to. 831.Pp 832Effectively what this does is is remove the callback from the chain of 833functions to be called when an authorization request is made, preventing 834from the listener from being entered in the future. 835.El 836.Pp 837.Nm 838provides no means for synchronization within listeners. 839It is the the programmer's responsibility to make sure data used by the 840listener is properly locked during its use, as it can be accessed 841simultaneously from the same listener called multiple times. 842It is also the programmer's responsibility to do garbage collection after 843the listener, possibly freeing any allocated data it used. 844.Pp 845The common method to do the above is by having a reference count to 846each listener. 847On entry to the listener, this reference count should be raised, and 848on exit -- lowered. 849.Pp 850During the removal of a listener, first 851.Fn kauth_scope_unlisten 852should be called to make sure the listener code will not be entered in 853the future. 854Then, the code should wait (possibly sleeping) until the reference count 855drops to zero. 856When that happens, it is safe to do the final cleanup. 857.Pp 858Listeners might sleep, so no locks can be held when calling an authorization 859wrapper. 860.\".Sh EXAMPLES 861.Sh SEE ALSO 862.Xr secmodel 9 863.Sh HISTORY 864The kernel authorization framework first appeared in Mac OS X 10.4. 865.Pp 866The kernel authorization framework in 867.Nx 868first appeared in 869.Nx 4.0 , 870and is a clean-room implementation based on Apple TN2127, available at 871http://developer.apple.com/technotes/tn2005/tn2127.html 872.Sh AUTHORS 873.An Elad Efrat Aq elad@NetBSD.org 874implemented the kernel authorization framework in 875.Nx . 876.Pp 877.An Jason R. Thorpe Aq thorpej@NetBSD.org 878provided guidance and answered questions about the Darwin implementation. 879.Sh ONE MORE THING 880The 881.Nm 882framework is dedicated to Brian Mitchell, one of the most talented people 883I know. 884Thanks for everything. 885