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