1.\" $NetBSD: kauth.9,v 1.53 2007/09/23 16:03:41 yamt 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 September 24, 2007 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 56.It kauth_cred_t 57Representing credentials that can be associated with an object. 58Includes user- and group-ids (real, effective, and save) as well as group 59membership information. 60.It kauth_scope_t 61Describes a scope. 62.It kauth_listener_t 63Describes a listener. 64.El 65.Ss Terminology 66.Nm 67operates in various 68.Dq scopes , 69each scope holding a group of 70.Dq listeners . 71.Pp 72Each listener works as a callback for when an authorization request within the 73scope is made. 74When such a request is made, all listeners on the scope are passed common 75information such as the credentials of the request context, an identifier for 76the requested operation, and possibly other information as well. 77.Pp 78Every listener examines the passed information and returns its decision 79regarding the requested operation. 80It can either allow, deny, or defer the operation -- in which case, the 81decision is left to the other listeners. 82.Pp 83For an operation to be allowed, all listeners must not return any deny 84or defer decisions. 85.Pp 86Scopes manage listeners that operate in the same aspect of the system. 87.Ss Kernel Programming Interface 88.Nm 89exports a KPI that allows developers both of 90.Nx 91and third-party products to authorize requests, access and modify credentials, 92create and remove scopes and listeners, and perform other miscellaneous operations on 93credentials. 94.Ss Authorization Requests 95.Nm 96provides a single authorization request routine, which all authorization 97requests go through. 98This routine dispatches the request to the listeners of the appropriate scope, 99together with four optional user-data variables, and returns the augmented 100result. 101.Pp 102It is declared as 103.Pp 104.Ft int Fn kauth_authorize_action "kauth_scope_t scope" "kauth_cred_t cred" \ 105"kauth_action_t op" "void *arg0" "void *arg1" "void *arg2" "void *arg3" 106.Pp 107An authorization request can return one of two possible values. 108Zero indicates success -- the operation is allowed; 109.Er EPERM 110(see 111.Xr errno 2 ) 112indicates failure -- the operation is denied. 113.Pp 114Each scope has its own authorization wrapper, to make it easy to call from various 115places by eliminating the need to specify the scope and/or cast values. 116The authorization wrappers are detailed in each scope's section. 117.Pp 118.Fn kauth_authorize_action 119has several special cases, when it will always allow the request. 120These are for when the request is issued by the kernel itself (indicated by the 121credentials being either 122.Dv NOCRED 123or 124.Dv FSCRED ) , 125or when there was no definitive decision from any of the listeners (i.e., it 126was not explicitly allowed or denied) and no security model was loaded. 127.Ss Generic Scope 128The generic scope, 129.Dq org.netbsd.kauth.generic , 130manages generic authorization requests in the kernel. 131.Pp 132The authorization wrapper for this scope is declared as 133.Pp 134.Ft int Fn kauth_authorize_generic "kauth_cred_t cred" "kauth_action_t op" \ 135"void *arg0" 136.Pp 137The following operations are available for this scope: 138.Bl -tag 139.It Dv KAUTH_GENERIC_ISSUSER 140Checks whether the credentials belong to the super-user. 141.Pp 142Using this request is strongly discouraged and should only be done as a 143temporary place-holder, as it is breaking the separation between the 144interface for authorization requests from the back-end implementation. 145.It Dv KAUTH_GENERIC_CANSEE 146Checks whether an object with one set of credentials can access 147information about another object, possibly with a different set of 148credentials. 149.Pp 150.Ar arg0 151contains the credentials of the object looked at. 152.Pp 153This request should be issued only in cases where generic credentials 154check is required; otherwise it is recommended to use the object-specific 155routines. 156.El 157.Ss System Scope 158The system scope, 159.Dq org.netbsd.kauth.system , 160manages authorization requests affecting the entire system. 161.Pp 162The authorization wrapper for this scope is declared as 163.Pp 164.Ft int Fn kauth_authorize_system "kauth_cred_t cred" \ 165"kauth_action_t op" "enum kauth_system_req req" "void *arg1" "void *arg2" \ 166"void *arg3" 167.Pp 168The following requests are available for this scope: 169.Bl -tag 170.It Dv KAUTH_SYSTEM_ACCOUNTING 171Check if enabling/disabling accounting allowed. 172.It Dv KAUTH_SYSTEM_CHROOT 173.Ar req 174can be any of the following: 175.Bl -tag 176.It Dv KAUTH_REQ_SYSTEM_CHROOT_CHROOT 177Check if calling 178.Xr chroot 2 179is allowed. 180.It Dv KAUTH_REQ_SYSTEM_CHROOT_FCHROOT 181Check if calling 182.Xr fchroot 2 183is allowed. 184.El 185.It Dv KAUTH_SYSTEM_DEBUG 186This request concentrates several debugging-related operations. 187.Ar req 188can be any of the following: 189.Bl -tag 190.It Dv KAUTH_REQ_SYSTEM_DEBUG_IPKDB 191Check if using 192.Xr ipkdb 4 193is allowed. 194.El 195.It Dv KAUTH_SYSTEM_FILEHANDLE 196Check if filehandle operations allowed. 197.It Dv KAUTH_SYSTEM_LKM 198Check if an LKM request is allowed. 199.Pp 200.Ar arg1 201is the command. 202.It Dv KAUTH_SYSTEM_MKNOD 203Check if creating devices is allowed. 204.It Dv KAUTH_SYSTEM_MOUNT 205Check if mount-related operations are allowed. 206.Pp 207.Ar req 208can be any of the following: 209.Bl -tag 210.It Dv KAUTH_REQ_SYSTEM_MOUNT_GET 211Check if retrieving information about a mount is allowed. 212.Ar arg1 213is a 214.Ft struct mount * 215with the mount structure in question, 216.Ar arg2 217is a 218.Ft void * 219with file-system specific data, if any. 220.It Dv KAUTH_REQ_SYSTEM_MOUNT_NEW 221Check if mounting a new file-system is allowed. 222.Pp 223.Ar arg1 224is the 225.Ft struct vnode * 226on which the file-system is to be mounted, 227.Ar arg2 228is an 229.Ft int 230with the mount flags, and 231.Ar arg3 232is a 233.Ft void * 234with file-system specific data, if any. 235.It Dv KAUTH_REQ_SYSTEM_MOUNT_UNMOUNT 236Checks if unmounting a file-system is allowed. 237.Pp 238.Ar arg1 239is a 240.Ft struct mount * 241with the mount in question. 242.It Dv KAUTH_REQ_SYSTEM_MOUNT_UPDATE 243Checks if updating an existing mount is allowed. 244.Pp 245.Ar arg1 246is the 247.Ft struct mount * 248of the existing mount, 249.Ar arg2 250is an 251.Ft int 252with the new mount flags, and 253.Ar arg3 254is a 255.Ft void * 256with file-system specific data, if any. 257.El 258.It Dv KAUTH_SYSTEM_REBOOT 259Check if rebooting is allowed. 260.It Dv KAUTH_SYSTEM_SETIDCORE 261Check if changing coredump settings for set-id processes is allowed. 262.It Dv KAUTH_SYSTEM_SWAPCTL 263Check if privileged 264.Xr swapctl 2 265requests are allowed. 266.It Dv KAUTH_SYSTEM_SYSCTL 267This requests operations related to 268.Xr sysctl 9 . 269.Ar req 270indicates the specific request and can be one of the following: 271.Bl -tag 272.It Dv KAUTH_REQ_SYSTEM_SYSCTL_ADD 273Check if adding a 274.Xr sysctl 9 275node is allowed. 276.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DELETE 277Check if deleting a 278.Xr sysctl 9 279node is allowed. 280.It Dv KAUTH_REQ_SYSTEM_SYSCTL_DESC 281Check if adding description to a 282.Xr sysctl 9 283node is allowed. 284.It Dv KAUTH_REQ_SYSTEM_SYSCTL_PRVT 285Check if accessing private 286.Xr sysctl 9 287nodes is allowed. 288.El 289.It Dv KAUTH_SYSTEM_TIME 290This request groups time-related operations. 291.Ar req 292can be any of the following: 293.Bl -tag 294.It Dv KAUTH_REQ_SYSTEM_TIME_ADJTIME 295Check if changing the time using 296.Xr adjtime 2 297is allowed. 298.It Dv KAUTH_REQ_SYSTEM_TIME_BACKWARDS 299Check if setting the time backwards is allowed. 300.It Dv KAUTH_REQ_SYSTEM_TIME_NTPADJTIME 301Check if setting the time using 302.Xr ntp_adjtime 2 303is allowed. 304.It Dv KAUTH_REQ_SYSTEM_TIME_SYSTEM 305Check if changing the time (usually via 306.Xr settimeofday 2 ) 307is allowed. 308.It Dv KAUTH_REQ_SYSTEM_TIME_RTCOFFSET 309Check if changing the RTC offset is allowed. 310.El 311.El 312.Ss Process Scope 313The process scope, 314.Dq org.netbsd.kauth.process , 315manages authorization requests related to processes in the system. 316.Pp 317The authorization wrapper for this scope is declared as 318.Pp 319.Ft int Fn kauth_authorize_process "kauth_cred_t cred" \ 320"kauth_action_t op" "struct proc *p" "void *arg1" "void *arg2" \ 321"void *arg3" 322.Pp 323The following operations are available for this scope: 324.Bl -tag 325.It Dv KAUTH_PROCESS_CANKTRACE 326Checks whether an object with one set of credentials can 327.Xr ktrace 1 328another process 329.Ar p , 330possibly with a different set of credentials. 331.It Dv KAUTH_PROCESS_CANPROCFS 332Checks whether object with passed credentials can use 333.Em procfs 334to access process 335.Ar p . 336.Pp 337.Ar arg1 338is the 339.Ft struct pfsnode * 340for the target element in the target process, and 341.Ar arg2 342is the access type, which can be either 343.Dv KAUTH_REQ_PROCESS_CANPROCFS_CTL , 344.Dv KAUTH_REQ_PROCESS_CANPROCFS_READ , 345.Dv KAUTH_REQ_PROCESS_CANPROCFS_RW , 346or 347.Dv KAUTH_REQ_PROCESS_CANPROCFS_WRITE , 348indicating 349.Em control , 350.Em read , 351.Em read-write , 352or 353.Em write 354access respectively. 355.It Dv KAUTH_PROCESS_CANPTRACE 356Checks whether object with passed credentials can use 357.Xr ptrace 2 358to access process 359.Ar p . 360.Pp 361.Ar arg1 362is the 363.Xr ptrace 2 364command. 365.It Dv KAUTH_PROCESS_CANSEE 366Checks whether an object with one set of credentials can access 367information about another process, possibly with a different set of 368credentials. 369.It Dv KAUTH_PROCESS_CANSIGNAL 370Checks whether an object with one set of credentials can post signals 371to another process. 372.Pp 373.Ar p 374is the process the signal is being posted to, and 375.Ar arg1 376is the signal number. 377.It Dv KAUTH_PROCESS_CANSYSTRACE 378Checks whether object with passed credentials can use 379.Xr systrace 4 380on process 381.Ar p . 382.It Dv KAUTH_PROCESS_CORENAME 383Checks whether the coredump name for the process 384.Ar p 385can be changed. 386.Pp 387.Ar arg1 388is the new corename. 389.It Dv KAUTH_PROCESS_NICE 390Checks whether the 391.Em nice 392value of 393.Ar p 394can be changed to 395.Ar arg1 . 396.It Dv KAUTH_PROCESS_RLIMIT 397Checks whether the 398.Em rlimit 399value for 400.Ar arg2 401in 402.Ar p 403can be set to 404.Ar arg1 . 405.It Dv KAUTH_PROCESS_SETID 406Check if changing the user- or group-ids, groups, or login-name for 407.Ar p 408is allowed. 409.It Dv KAUTH_PROCESS_STOPFLAG 410Check if setting the stop flags for 411.Xr exec 3 , 412.Xr exit 3 , 413and 414.Xr fork 2 415is allowed. 416.Pp 417.Ar arg1 418indicates the flag, and can be either 419.Dv P_STOPEXEC , 420.Dv P_STOPEXIT , 421or 422.Dv P_STOPFORK 423respectively. 424.El 425.Ss Network Scope 426The network scope, 427.Dq org.netbsd.kauth.network , 428manages networking-related authorization requests in the kernel. 429.Pp 430The authorization wrapper for this scope is declared as 431.Pp 432.Ft int Fn kauth_authorize_network "kauth_cred_t cred" "kauth_action_t op" \ 433"enum kauth_network_req req" "void *arg1" "void *arg2" "void *arg3" 434.Pp 435The following operations are available for this scope: 436.Bl -tag 437.It Dv KAUTH_NETWORK_ALTQ 438Checks if an ALTQ operation is allowed. 439.Pp 440.Ar req 441indicates the ALTQ subsystem in question, and can be one of the following: 442.Pp 443.Bl -tag -compact 444.It Dv KAUTH_REQ_NETWORK_ALTQ_AFMAP 445.It Dv KAUTH_REQ_NETWORK_ALTQ_BLUE 446.It Dv KAUTH_REQ_NETWORK_ALTQ_CBQ 447.It Dv KAUTH_REQ_NETWORK_ALTQ_CDNR 448.It Dv KAUTH_REQ_NETWORK_ALTQ_CONF 449.It Dv KAUTH_REQ_NETWORK_ALTQ_FIFOQ 450.It Dv KAUTH_REQ_NETWORK_ALTQ_HFSC 451.It Dv KAUTH_REQ_NETWORK_ALTQ_JOBS 452.It Dv KAUTH_REQ_NETWORK_ALTQ_PRIQ 453.It Dv KAUTH_REQ_NETWORK_ALTQ_RED 454.It Dv KAUTH_REQ_NETWORK_ALTQ_RIO 455.It Dv KAUTH_REQ_NETWORK_ALTQ_WFQ 456.El 457.It Dv KAUTH_NETWORK_BIND 458Checks if a 459.Xr bind 2 460request is allowed. 461.Pp 462.Ar req 463allows to indicate the type of the request to structure listeners and callers 464easier. 465Supported request types: 466.Bl -tag 467.It Dv KAUTH_REQ_NETWORK_BIND_PRIVPORT 468Checks if binding to a privileged/reserved port is allowed. 469.El 470.It Dv KAUTH_NETWORK_FIREWALL 471Checks if firewall-related operations are allowed. 472.Pp 473.Ar req 474indicates the sub-action, and can be one of the following: 475.Bl -tag 476.It Dv KAUTH_REQ_NETWORK_FIREWALL_FW 477Modification of packet filtering rules. 478.It Dv KAUTH_REQ_NETWORK_FIREWALL_NAT 479Modification of NAT rules. 480.El 481.It Dv KAUTH_NETWORK_INTERFACE 482Checks if network interface-related operations are allowed. 483.Pp 484.Ar arg1 485is (optionally) the 486.Ft struct ifnet * 487associated with the interface. 488.Ar arg2 489is (optionally) an 490.Ft int 491describing the interface-specific operation. 492.Ar arg3 493is (optionally) a pointer to the interface-specific request structure. 494.Ar req 495indicates the sub-action, and can be one of the following: 496.Bl -tag 497.It Dv KAUTH_REQ_NETWORK_INTERFACE_GET 498Check if retrieving information from the device is allowed. 499.It Dv KAUTH_REQ_NETWORK_INTERFACE_GETPRIV 500Check if retrieving privileged information from the device is allowed. 501.It Dv KAUTH_REQ_NETWORK_INTERFACE_SET 502Check if setting parameters on the device is allowed. 503.It Dv KAUTH_REQ_NETWORK_INTERFACE_SETPRIV 504Check if setting privileged parameters on the device is allowed. 505.El 506.Pp 507Note that unless the 508.Ft struct ifnet * 509for the interface was passed in 510.Ar arg1 , 511there's no way to tell what structure 512.Ar arg3 513is. 514.It Dv KAUTH_NETWORK_FORWSRCRT 515Checks whether status of forwarding of source-routed packets can be modified 516or not. 517.It Dv KAUTH_NETWORK_ROUTE 518Checks if a routing-related request is allowed. 519.Pp 520.Ar arg1 521is the 522.Ft struct rt_msghdr * 523for the request. 524.It Dv KAUTH_NETWORK_SOCKET 525Checks if a socket related operation is allowed. 526.Pp 527.Ar req 528allows to indicate the type of the request to structure listeners and callers 529easier. 530Supported request types: 531.Bl -tag 532.It Dv KAUTH_REQ_NETWORK_SOCKET_RAWSOCK 533Checks if opening a raw socket is allowed. 534.It Dv KAUTH_REQ_NETWORK_SOCKET_OPEN 535Checks if opening a socket is allowed. 536.Ar arg1 , arg2 , 537and 538.Ar arg3 539are all 540.Ft int 541parameters describing the domain, socket type, and protocol, 542respectively. 543.It Dv KAUTH_REQ_NETWORK_SOCKET_CANSEE 544Checks if looking at the socket passed is allowed. 545.Pp 546.Ar arg1 547is a 548.Ft struct socket * 549describing the socket. 550.El 551.El 552.Ss Machine-dependent Scope 553The machine-dependent (machdep) scope, 554.Dq org.netbsd.kauth.machdep , 555manages machine-dependent authorization requests in the kernel. 556.Pp 557The authorization wrapper for this scope is declared as 558.Pp 559.Ft int Fn kauth_authorize_machdep "kauth_cred_t cred" "kauth_action_t op" \ 560"void *arg0" "void *arg1" "void *arg2" "void *arg3" 561.Pp 562The actions on this scope provide a set that may or may not affect all 563platforms. 564Below is a list of available actions, along with which platforms are affected 565by each. 566.Bl -tag 567.It Dv KAUTH_MACHDEP_IOPERM_GET 568Request to get the I/O permission level. 569Affects 570.Em amd64 , 571.Em i386 , 572.Em xen . 573.It Dv KAUTH_MACHDEP_IOPERM_SET 574Request to set the I/O permission level. 575Affects 576.Em amd64 , 577.Em i386 , 578.Em xen . 579.It Dv KAUTH_MACHDEP_IOPL 580Request to set the I/O privilege level. 581Affects 582.Em amd64 , 583.Em i386 , 584.Em xen . 585.It Dv KAUTH_MACHDEP_LDT_GET 586Request to get the LDT (local descriptor table). 587Affects 588.Em amd64 , 589.Em i386 , 590.Em xen . 591.It Dv KAUTH_MACHDEP_LDT_SET 592Request to set the LDT (local descriptor table). 593Affects 594.Em amd64 , 595.Em i386 , 596.Em xen . 597.It Dv KAUTH_MACHDEP_MTRR_GET 598Request to get the MTRR (memory type range registers). 599Affects 600.Em amd64 , 601.Em i386 , 602.Em xen . 603.It Dv KAUTH_MACHDEP_MTRR_SET 604Request to set the MTRR (memory type range registers). 605Affects 606.Em amd64 , 607.Em i386 , 608.Em xen . 609.It Dv KAUTH_MACHDEP_UNMANAGEDMEM 610Request to access unmanaged memory. 611Affects 612.Em alpha , 613.Em amd64 , 614.Em arm , 615.Em i386 , 616.Em pc532 , 617.Em powerpc , 618.Em sh3 , 619.Em sh5 , 620.Em vax , 621.Em xen . 622.El 623.Ss Device Scope 624The device scope, 625.Dq org.netbsd.kauth.device , 626manages authorization requests related to devices on the system. 627Devices can be, for example, terminals, tape drives, and any other hardware. 628Network devices specifically are handled by the 629.Em network 630scope. 631.Pp 632In addition to the standard authorization wrapper: 633.Pp 634.Ft int Fn kauth_authorize_device "kauth_cred_t cred" "kauth_action_t op" \ 635"void *arg0" "void *arg1" "void *arg2" "void *arg3" 636.Pp 637this scope provides authorization wrappers for various device types. 638.Pp 639.Ft int Fn kauth_authorize_device_tty "kauth_cred_t cred" "kauth_action_t op" \ 640"struct tty *tty" 641.Pp 642Authorizes requests for 643.Em terminal devices 644on the system. 645The third argument, 646.Ar tty , 647is the terminal device in question. 648It is passed to the listener as 649.Ar arg0 . 650The second argument, 651.Ar op , 652is the action and can be one of the following: 653.Bl -tag 654.It Dv KAUTH_DEVICE_TTY_OPEN 655Open the terminal device pointed to by 656.Ar tty . 657.It Dv KAUTH_DEVICE_TTY_PRIVSET 658Set privileged settings on the terminal device pointed to by 659.Ar tty . 660.El 661.Pp 662.Ft int Fn kauth_authorize_device_spec "kauth_cred_t cred" \ 663"enum kauth_device_req req" "struct vnode *vp" 664.Pp 665Authorizes requests for 666.Em special files , 667usually disk devices, but also direct memory access, on the system. 668.Pp 669It passes 670.Dv KAUTH_DEVICE_RAWIO_SPEC 671as the action to the listener, and accepts two arguments. 672.Ar req , 673passed to the listener as 674.Ar arg0 , 675is access requested, and can be one of 676.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_READ , 677.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_WRITE , 678or 679.Dv KAUTH_REQ_DEVICE_RAWIO_SPEC_RW , 680representing read, write, or both read/write access respectively. 681.Ar vp 682is the vnode of the special file in question, and is passed to the listener as 683.Ar arg1 . 684.Pp 685Keep in mind that it is the responsibility of the security model developer to 686check whether the underlying device is a disk or the system memory, using 687.Fn iskmemdev : 688.Bd -literal -offset indent 689if ((vp-\*[Gt]v_type == VCHR) \*[Am]\*[Am] 690 iskmemdev(vp-\*[Gt]v_un.vu_specinfo-\*[Gt]si_rdev)) 691 /* system memory access */ 692.Ed 693.Pp 694.Ft int Fn kauth_authorize_device_passthru "kauth_cred_t cred" "dev_t dev" \ 695"u_long mode" "void *data" 696.Pp 697Authorizes hardware 698.Em passthru 699requests, or user commands passed directly to the hardware. 700These have the potential of resulting in direct disk and/or memory access. 701.Pp 702It passes 703.Dv KAUTH_DEVICE_RAWIO_PASSTHRU 704as the action to the listener, and accepts three arguments. 705.Ar dev , 706passed as 707.Ar arg1 708to the listener, is the device for which the request is made. 709.Ar mode , 710passed as 711.Ar arg0 712to the listener, is a generic representation of the access mode requested. 713It can be one or more (binary-OR'd) of the following: 714.Pp 715.Bl -tag -offset indent -compact 716.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READ 717.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_READCONF 718.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITE 719.It KAUTH_REQ_DEVICE_RAWIO_PASSTHRU_WRITECONF 720.El 721.Pp 722.Ar data , 723passed as 724.Ar arg2 725to the listener, is device-specific data that may be associated with the 726request. 727.Ss Credentials Scope 728The credentials scope, 729.Dq org.netbsd.kauth.cred , 730is a special scope used internally by the 731.Nm 732framework to provide hooking to credential-related operations. 733.Pp 734It is a 735.Dq notify-only 736scope, allowing hooking operations such as initialization of new credentials, 737credential inheritance during a fork, and copying and freeing of credentials. 738The main purpose for this scope is to give a security model a way to control 739the aforementioned operations, especially in cases where the credentials 740hold security model-private data. 741.Pp 742Notifications are made using the following function, which is internal to 743.Nm : 744.Pp 745.Ft int Fn kauth_cred_hook "kauth_cred_t cred" "kauth_action_t action" \ 746"void *arg0" "void *arg1" 747.Pp 748With the following actions: 749.Bl -tag 750.It Dv KAUTH_CRED_COPY 751The credentials are being copied. 752.Ar cred 753are the credentials of the lwp context doing the copy, and 754.Ar arg0 755and 756.Ar arg1 757are both 758.Ft kauth_cred_t 759representing the 760.Dq from 761and 762.Dq to 763credentials, respectively. 764.It Dv KAUTH_CRED_FORK 765The credentials are being inherited from a parent to a child process during a 766fork. 767.Pp 768.Ar cred 769are the credentials of the lwp context doing the copy, and 770.Ar arg0 771and 772.Ar arg1 773are both 774.Ft struct proc * 775of the parent and child processes, respectively. 776.It Dv KAUTH_CRED_FREE 777The credentials in 778.Ar cred 779are being freed. 780.It Dv KAUTH_CRED_INIT 781The credentials in 782.Ar cred 783are being initialized. 784.El 785.Pp 786Since this is a notify-only scope, all listeners are required to return 787.Dv KAUTH_RESULT_ALLOW . 788.Ss Credentials Accessors and Mutators 789.Nm 790has a variety of accessor and mutator routines to handle 791.Ft kauth_cred_t 792objects. 793.Pp 794The following routines can be used to access and modify the user- and 795group-ids in a 796.Ft kauth_cred_t : 797.Bl -tag 798.It Ft uid_t Fn kauth_cred_getuid "kauth_cred_t cred" 799Returns the real user-id from 800.Ar cred . 801.It Ft uid_t Fn kauth_cred_geteuid "kauth_cred_t cred" 802Returns the effective user-id from 803.Ar cred . 804.It Ft uid_t Fn kauth_cred_getsvuid "kauth_cred_t cred" 805Returns the saved user-id from 806.Ar cred . 807.It Ft void Fn kauth_cred_setuid "kauth_cred_t cred" "uid_t uid" 808Sets the real user-id in 809.Ar cred 810to 811.Ar uid . 812.It Ft void Fn kauth_cred_seteuid "kauth_cred_t cred" "uid_t uid" 813Sets the effective user-id in 814.Ar cred 815to 816.Ar uid . 817.It Ft void Fn kauth_cred_setsvuid "kauth_cred_t cred" "uid_t uid" 818Sets the saved user-id in 819.Ar cred 820to 821.Ar uid . 822.It Ft gid_t Fn kauth_cred_getgid "kauth_cred_t cred" 823Returns the real group-id from 824.Ar cred . 825.It Ft gid_t Fn kauth_cred_getegid "kauth_cred_t cred" 826Returns the effective group-id from 827.Ar cred . 828.It Ft gid_t Fn kauth_cred_getsvgid "kauth_cred_t cred" 829Returns the saved group-id from 830.Ar cred . 831.It Ft void Fn kauth_cred_setgid "kauth_cred_t cred" "gid_t gid" 832Sets the real group-id in 833.Ar cred 834to 835.Ar gid . 836.It Ft void Fn kauth_cred_setegid "kauth_cred_t cred" "gid_t gid" 837Sets the effective group-id in 838.Ar cred 839to 840.Ar gid . 841.It Ft void Fn kauth_cred_setsvgid "kauth_cred_t cred" "gid_t gid" 842Sets the saved group-id in 843.Ar cred 844to 845.Ar gid . 846.It Ft u_int Fn kauth_cred_getrefcnt "kauth_cred_t cred" 847Return the reference count for 848.Ar cred . 849.El 850.Pp 851The following routines can be used to access and modify the group 852list in a 853.Ft kauth_cred_t : 854.Bl -tag 855.It Ft int Fn kauth_cred_ismember_gid "kauth_cred_t cred" "gid_t gid" \ 856"int *resultp" 857Checks if the group-id 858.Ar gid 859is a member in the group list of 860.Ar cred . 861.Pp 862If it is, 863.Ar resultp 864will be set to one, otherwise, to zero. 865.Pp 866The return value is an error code, or zero for success. 867.It Ft u_int Fn kauth_cred_ngroups "kauth_cred_t cred" 868Return the number of groups in the group list of 869.Ar cred . 870.It Ft gid_t Fn kauth_cred_group "kauth_cred_t cred" "u_int idx" 871Return the group-id of the group at index 872.Ar idx 873in the group list of 874.Ar cred . 875.It Ft int Fn kauth_cred_setgroups "kauth_cred_t cred" "gid_t *groups" \ 876"size_t ngroups" "uid_t gmuid" "enum uio_seg seg" 877Copy 878.Ar ngroups 879groups from array pointed to by 880.Ar groups 881to the group list in 882.Ar cred , 883adjusting the number of groups in 884.Ar cred 885appropriately. 886.Ar seg 887should be either 888.Dv UIO_USERSPACE 889or 890.Dv UIO_SYSSPACE 891indicating whether 892.Ar groups 893is a user or kernel space address. 894.Pp 895Any groups remaining will be set to an invalid value. 896.Pp 897.Ar gmuid 898is unused for now, and to maintain interface compatibility with the Darwin 899KPI. 900.Pp 901The return value is an error code, or zero for success. 902.It Ft int Fn kauth_cred_getgroups "kauth_cred_t cred" "gid_t *groups" \ 903"size_t ngroups" "enum uio_seg seg" 904Copy 905.Ar ngroups 906groups from the group list in 907.Ar cred 908to the buffer pointed to by 909.Ar groups . 910.Ar seg 911should be either 912.Dv UIO_USERSPACE 913or 914.Dv UIO_SYSSPACE 915indicating whether 916.Ar groups 917is a user or kernel space address. 918.Pp 919The return value is an error code, or zero for success. 920.El 921.Ss Credential Private Data 922.Nm 923provides an interface to allow attaching security-model private data to 924credentials. 925.Pp 926The use of this interface has two parts that can be divided to direct and 927indirect control of the private-data. 928Directly controlling the private data is done by using the below routines, 929while the indirect control is often dictated by events such as process 930fork, and is handled by listening on the credentials scope (see above). 931.Pp 932Attaching private data to credentials works by registering a key to serve 933as a unique identifier, distinguishing various sets of private data that 934may be associated with the credentials. 935Registering, and deregistering, a key is done by using these routines: 936.Pp 937.Bl -tag 938.It Ft int Fn kauth_register_key "const char *name" "kauth_key_t *keyp" 939Register new key for private data for 940.Ar name 941(usually, the security model name). 942.Ar keyp 943will be used to return the key to be used in further calls. 944.Pp 945The function returns 0 on success and an error code (see 946.Xr errno 2 ) 947on failure. 948.It Ft int Fn kauth_deregister_key "kauth_key_t key" 949Deregister private data key 950.Ar key . 951.El 952.Pp 953Once registered, private data may be manipulated by the following routines: 954.Bl -tag 955.It Ft void Fn kauth_cred_setdata "kauth_cred_t cred" "kauth_key_t key" \ 956"void *data" 957Set private data for 958.Ar key 959in 960.Ar cred 961to be 962.Ar data . 963.It Ft void * Fn kauth_cred_getdata "kauth_cred_t cred" "kauth_key_t key" 964Retrieve private data for 965.Ar key 966in 967.Ar cred . 968.El 969.Pp 970Note that it is required to use the above routines every time the private 971data is changed, i.e., using 972.Fn kauth_cred_getdata 973and later modifying the private data should be accompanied by a call to 974.Fn kauth_cred_setdata 975with the 976.Dq new 977private data. 978.Ss Credential Inheritance and Reference Counting 979.Nm 980provides an interface for handling shared credentials. 981.Pp 982When a 983.Ft kauth_cred_t 984is first allocated, its reference count is set to 1. 985However, with time, its reference count can grow as more objects (processes, 986LWPs, files, etc.) reference it. 987.Pp 988The following routines are available for managing credentials reference 989counting: 990.Bl -tag 991.It Ft void Fn kauth_cred_hold "kauth_cred_t cred" 992Increases reference count to 993.Ar cred 994by one. 995.It Ft void Fn kauth_cred_free "kauth_cred_t cred" 996Decreases the reference count to 997.Ar cred 998by one. 999.Pp 1000If the reference count dropped to zero, the memory used by 1001.Ar cred 1002will be freed. 1003.El 1004.Pp 1005Credential inheritance happens during a 1006.Xr fork 2 , 1007and is handled by the following function: 1008.Pp 1009.Ft void Fn kauth_proc_fork "struct proc *parent" "struct proc *child" 1010.Pp 1011When called, it references the parent's credentials from the child, 1012and calls the credentials scope's hook with the 1013.Dv KAUTH_CRED_FORK 1014action to allow security model-specific handling of the inheritance 1015to take place. 1016.Ss Credentials Memory Management 1017Data-structures for credentials, listeners, and scopes are allocated from 1018memory pools managed by the 1019.Xr pool 9 1020subsystem. 1021.Pp 1022The 1023.Ft kauth_cred_t 1024objects have their own memory management routines: 1025.Bl -tag 1026.It Ft kauth_cred_t Fn kauth_cred_alloc "void" 1027Allocates a new 1028.Ft kauth_cred_t , 1029initializes its lock, and sets its reference count to one. 1030.El 1031.Ss Conversion Routines 1032Sometimes it might be necessary to convert a 1033.Ft kauth_cred_t 1034to userland's view of credentials, a 1035.Ft struct uucred , 1036or vice versa. 1037.Pp 1038The following routines are available for these cases: 1039.Bl -tag 1040.It Ft void Fn kauth_uucred_to_cred "kauth_cred_t cred" "const struct uucred *uucred" 1041Convert userland's view of credentials to a 1042.Ft kauth_cred_t . 1043.Pp 1044This includes effective user- and group-ids, a number of groups, and a group 1045list. 1046The reference count is set to one. 1047.Pp 1048Note that 1049.Nm 1050will try to copy as many groups as can be held inside a 1051.Ft kauth_cred_t . 1052.It Ft void Fn kauth_cred_to_uucred "struct uucred *uucred" "const kauth_cred_t cred" 1053Convert 1054.Ft kauth_cred_t 1055to userland's view of credentials. 1056.Pp 1057This includes effective user- and group-ids, a number of groups, and a group 1058list. 1059.Pp 1060Note that 1061.Nm 1062will try to copy as many groups as can be held inside a 1063.Ft struct uucred . 1064.It Ft int Fn kauth_cred_uucmp "kauth_cred_t cred" "struct uucred *uucred" 1065Compares 1066.Ar cred 1067with the userland credentials in 1068.Ar uucred . 1069.Pp 1070Common values that will be compared are effective user- and group-ids, and 1071the group list. 1072.El 1073.Ss Miscellaneous Routines 1074Other routines provided by 1075.Nm 1076are: 1077.Bl -tag 1078.It Ft void Fn kauth_cred_clone "kauth_cred_t cred1" "kauth_cred_t cred2" 1079Clone credentials from 1080.Ar cred1 1081to 1082.Ar cred2 , 1083except for the lock and reference count. 1084.Pp 1085.It Ft kauth_cred_t Fn kauth_cred_dup "kauth_cred_t cred" 1086Duplicate 1087.Ar cred . 1088.Pp 1089What this routine does is call 1090.Fn kauth_cred_alloc 1091followed by a call to 1092.Fn kauth_cred_clone . 1093.It Ft kauth_cred_t Fn kauth_cred_copy "kauth_cred_t cred" 1094Works like 1095.Fn kauth_cred_dup , 1096except for a few differences. 1097.Pp 1098If 1099.Ar cred 1100already has a reference count of one, it will be returned. 1101Otherwise, a new 1102.Ft kauth_cred_t 1103will be allocated and the credentials from 1104.Ar cred 1105will be cloned to it. 1106Last, a call to 1107.Fn kauth_cred_free 1108for 1109.Ar cred 1110will be done. 1111.It Ft kauth_cred_t Fn kauth_cred_get "void" 1112Return the credentials associated with the current LWP. 1113.El 1114.Ss Scope Management 1115.Nm 1116provides routines to manage the creation and deletion of scopes on the 1117system. 1118.Pp 1119Note that the built-in scopes, the 1120.Dq generic 1121scope and the 1122.Dq process 1123scope, can't be deleted. 1124.Bl -tag 1125.It Ft kauth_scope_t Fn kauth_register_scope "const char *id" \ 1126"kauth_scope_callback_t cb" "void *cookie" 1127Register a new scope on the system. 1128.Ar id 1129is the name of the scope, usually in reverse DNS-like notation. 1130For example, 1131.Dq org.netbsd.kauth.myscope . 1132.Ar cb 1133is the default listener, to which authorization requests for this scope 1134will be dispatched to. 1135.Ar cookie 1136is optional user-data that will be passed to all listeners 1137during authorization on the scope. 1138.It Ft void Fn kauth_deregister_scope "kauth_scope_t scope" 1139Deregister 1140.Ar scope 1141from the scopes available on the system, and free the 1142.Ft kauth_scope_t 1143object 1144.Ar scope . 1145.El 1146.Ss Listener Management 1147Listeners in 1148.Nm 1149are authorization callbacks that are called during an authorization 1150request in the scope which they belong to. 1151.Pp 1152When an authorization request is made, all listeners associated with 1153a scope are called to allow, deny, or defer the request. 1154.Pp 1155It is enough for one listener to deny the request in order for the 1156request to be denied; but all listeners are called during an authorization 1157process none-the-less. 1158All listeners are required to allow the request for it to be granted, 1159and in a case where all listeners defer the request -- leaving the decision 1160for other listeners -- the request is denied. 1161.Pp 1162The following KPI is provided for the management of listeners: 1163.Bl -tag 1164.It Ft kauth_listener_t Fn kauth_listen_scope "const char *id" \ 1165"kauth_scope_callback_t cb" "void *cookie" 1166Create a new listener on the scope with the id 1167.Ar id , 1168setting the default listener to 1169.Ar cb . 1170.Ar cookie 1171is optional user-data that will be passed to the listener when called 1172during an authorization request. 1173.It Ft void Fn kauth_unlisten_scope "kauth_listener_t listener" 1174Removes 1175.Ar listener 1176from the scope which it belongs to, ensuring it won't be called again, 1177and frees the 1178.Ft kauth_listener_t 1179object 1180.Ar listener . 1181.El 1182.Pp 1183.Nm 1184provides no means for synchronization within listeners. 1185It is the the programmer's responsibility to make sure data used by the 1186listener is properly locked during its use, as it can be accessed 1187simultaneously from the same listener called multiple times. 1188It is also the programmer's responsibility to do garbage collection after 1189the listener, possibly freeing any allocated data it used. 1190.Pp 1191The common method to do the above is by having a reference count to 1192each listener. 1193On entry to the listener, this reference count should be raised, and 1194on exit -- lowered. 1195.Pp 1196During the removal of a listener, first 1197.Fn kauth_scope_unlisten 1198should be called to make sure the listener code will not be entered in 1199the future. 1200Then, the code should wait (possibly sleeping) until the reference count 1201drops to zero. 1202When that happens, it is safe to do the final cleanup. 1203.Pp 1204Listeners might sleep, so no locks can be held when calling an authorization 1205wrapper. 1206.Sh EXAMPLES 1207Older code had no abstraction of the security model, so most privilege 1208checks looked like this: 1209.Bd -literal -offset indent 1210if (suser(cred, \*[Am]acflag) == 0) 1211 /* allow privileged operation */ 1212.Ed 1213.Pp 1214Using the new interface, you must ask for a specific privilege explicitly. 1215For example, checking whether it is possible to open a socket would look 1216something like this: 1217.Bd -literal -offset indent 1218if (kauth_authorize_network(cred, KAUTH_NETWORK_SOCKET, 1219 KAUTH_REQ_NETWORK_SOCKET_OPEN, PF_INET, SOCK_STREAM, 1220 IPPROTO_TCP) == 0) 1221 /* allow opening the socket */ 1222.Ed 1223.Pp 1224Note that the 1225.Em securelevel 1226implications were also integrated into the 1227.Nm 1228framework so you don't have to note anything special in the call to the 1229authorization wrapper, but rather just have to make sure the security 1230model handles the request as you expect it to. 1231.Pp 1232To do that you can just 1233.Xr grep 1 1234in the relevant security model directory and have a look at the code. 1235.Sh EXTENDING KAUTH 1236Although 1237.Nm 1238provides a large set of both detailed and more or less generic requests, 1239it might be needed eventually to introduce more scopes, actions, or 1240requests. 1241.Pp 1242Adding a new scope should happen only when an entire subsystem is 1243introduced and it is assumed other parts of the kernel may want to 1244interfere with its inner-workings. 1245When a subsystem that has the potential of impacting the security 1246if the system is introduced, existing security modules must be updated 1247to also handle actions on the newly added scope. 1248.Pp 1249New actions should be added when sets of operations not covered at all 1250belong in an already existing scope. 1251.Pp 1252Requests (or sub-actions) can be added as subsets of existing actions 1253when an operation that belongs in an already covered area is introduced. 1254.Pp 1255Note that all additions should include updates to this manual, the 1256security models shipped with 1257.Nx , 1258and the example skeleton security model. 1259.Sh SEE ALSO 1260.Xr secmodel 9 1261.Sh HISTORY 1262The kernel authorization framework first appeared in Mac OS X 10.4. 1263.Pp 1264The kernel authorization framework in 1265.Nx 1266first appeared in 1267.Nx 4.0 , 1268and is a clean-room implementation based on Apple TN2127, available at 1269http://developer.apple.com/technotes/tn2005/tn2127.html 1270.Sh AUTHORS 1271.An Elad Efrat Aq elad@NetBSD.org 1272implemented the kernel authorization framework in 1273.Nx . 1274.Pp 1275.An Jason R. Thorpe Aq thorpej@NetBSD.org 1276provided guidance and answered questions about the Darwin implementation. 1277.Sh ONE MORE THING 1278The 1279.Nm 1280framework is dedicated to Brian Mitchell, one of the most talented people 1281I know. 1282Thanks for everything. 1283