From owner-p4-projects@FreeBSD.ORG Tue Nov 14 20:47:02 2006 Return-Path: X-Original-To: p4-projects@freebsd.org Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 8595116A532; Tue, 14 Nov 2006 20:47:02 +0000 (UTC) X-Original-To: perforce@freebsd.org Delivered-To: perforce@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4A5A416A517 for ; Tue, 14 Nov 2006 20:47:02 +0000 (UTC) (envelope-from millert@freebsd.org) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id 1EA1943E31 for ; Tue, 14 Nov 2006 20:40:51 +0000 (GMT) (envelope-from millert@freebsd.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.13.6/8.13.6) with ESMTP id kAEKeitU048163 for ; Tue, 14 Nov 2006 20:40:44 GMT (envelope-from millert@freebsd.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.6/8.13.4/Submit) id kAEKehNB048160 for perforce@freebsd.org; Tue, 14 Nov 2006 20:40:43 GMT (envelope-from millert@freebsd.org) Date: Tue, 14 Nov 2006 20:40:43 GMT Message-Id: <200611142040.kAEKehNB048160@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to millert@freebsd.org using -f From: Todd Miller To: Perforce Change Reviews Cc: Subject: PERFORCE change 109989 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 14 Nov 2006 20:47:02 -0000 http://perforce.freebsd.org/chv.cgi?CH=109989 Change 109989 by millert@millert_g5tower on 2006/11/14 20:40:04 Update libmac docs from FreeBSD with a few minor fixes. Affected files ... .. //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac.3#3 edit .. //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_get.3#3 edit .. //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_prepare.3#2 edit .. //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_set.3#2 edit .. //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_text.3#2 edit Differences ... ==== //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac.3#3 (text+ko) ==== @@ -28,7 +28,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libc/posix1e/mac.3,v 1.13 2003/05/22 13:02:27 ru Exp $ +.\" $FreeBSD: src/lib/libc/posix1e/mac.3,v 1.15 2005/07/31 03:30:44 keramida Exp $ .\" .Dd April 19, 2003 .Dt MAC 3 @@ -177,7 +177,7 @@ .Fx POSIX.1e implementation page for more information. -However, the resemblence of these APIs to the POSIX APIs is only loose, +However, the resemblance of these APIs to the POSIX APIs is only loose, as the POSIX APIs were unable to express many notions required for flexible and extensible access control. .Sh HISTORY ==== //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_get.3#3 (text+ko) ==== @@ -1,4 +1,4 @@ -.\" Copyright (c) 2001 Networks Associates Technology, Inc. +.\" Copyright (c) 2001, 2004 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris @@ -28,19 +28,21 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libc/posix1e/mac_get.3,v 1.5 2003/01/15 03:03:05 chris Exp $ +.\" $FreeBSD: src/lib/libc/posix1e/mac_get.3,v 1.10 2004/06/30 20:09:09 ru Exp $ .\" .Dd December 21, 2001 .Dt MAC_GET 3 .Os .Sh NAME .Nm mac_get_file , +.Nm mac_get_link , .Nm mac_get_fd , .Nm mac_get_lctx , .Nm mac_get_lcid , +.Nm mac_get_peer , .Nm mac_get_pid , .Nm mac_get_proc -.Nd get the label of a file, socket, socket peer or process +.Nd get the label of a file, socket, login context, mount point, socket peer or process .Sh LIBRARY The MAC Framework Library (libmac, -lmac) .Sh SYNOPSIS @@ -48,6 +50,8 @@ .Ft int .Fn mac_get_file "const char *path" "mac_t label" .Ft int +.Fn mac_get_link "const char *path" "mac_t label" +.Ft int .Fn mac_get_fd "int fd" "mac_t label" .Ft int .Fn mac_get_lcid "pid_t lcid" "mac_t label" @@ -56,60 +60,63 @@ .Ft int .Fn mac_get_mount "const char *path" "mac_t label" .Ft int +.Fn mac_get_peer "int fd" "mac_t label" +.Ft int .Fn mac_get_pid "pid_t pid" "mac_t label" .Ft int .Fn mac_get_proc "mac_t label" .Sh DESCRIPTION The .Fn mac_get_file -and +function returns the label associated with a file specified by +.Fa path . +The +.Fn mac_get_link +function is the same as +.Fn mac_get_file , +except that it does not follow symlinks. +.Pp +The .Fn mac_get_fd -functions fill in -.Fa label -(which must first be allocated by -.Xr mac_prepare 3 ) -with the MAC label associated with the file referenced by -.Fa path -or the file descriptor specified by -.Fa fd , -respectively. -Note that this function will fail on socket descriptors. -For information on -getting MAC labels on socket descriptors see -.Xr getsockopt 2 . +function returns the label associated with an object referenced by +the specified file descriptor. +Note that in the case of a file system socket, the label returned will +be the socket label, which may be different from the label of the +on-disk node acting as a rendezvous for the socket. .Pp The +.Fn mac_get_lctx +and +.Fn mac_get_lcid +functions return the label associated with the Login Context of +the requesting process or the specified Login Context, respectively. +.Pp .Fn mac_get_mount -function fills in -.Fa label -(which must first be allocated by -.Xr mac_prepare 3 ) -with the MAC label associated with the mount point referenced by +function returns the label associated with the mount point described by .Fa path . .Pp The -.Fn mac_get_lctx -and -.Fn mac_get_lcid -functions fill in -.Fa label -(which must first be allocated by -.Xr mac_prepare 3 ) -with the MAC label associated -with the Login Context of the requesting process -or the specified Login Context, respectively. +.Fn mac_get_peer +system call returns the label associated with the remote endpoint of +a socket. The exact semantics of this call will depend on the protocol +domain, communications type, and endpoint. Typically this label will +be cached when a connection-oriented protocol instance is first set up, +and is undefined for datagram protocols. .Pp The +.Fn mac_get_pid +and .Fn mac_get_proc -and -.Fn mac_get_pid -functions fill in -.Fa label -(which must first be allocated by -.Xr mac_prepare 3 ) -with the MAC label associated -with the requesting process -or the specified process, respectively. +functions return the process label associated with an arbitrary +process ID, or the current process. +.Pp +Label storage for use with these functions must first be allocated and +prepared using the +.Xr mac_prepare 3 +functions. +When an application is done using a label, the memory may be returned +using +.Xr mac_free 3 . .Sh ERRORS .Bl -tag -width Er .It Bq Er EACCES ==== //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_prepare.3#2 (text+ko) ==== @@ -1,4 +1,4 @@ -.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" Copyright (c) 2002, 2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" This software was developed for the FreeBSD Project by Chris @@ -30,18 +30,20 @@ .\" .\" $FreeBSD: src/lib/libc/posix1e/mac_prepare.3,v 1.3 2003/04/20 04:43:56 rwatson Exp $ .\" -.Dd December 12, 2002 +.Dd August 22, 2003 .Os .Dt MAC_PREPARE 3 .Sh NAME -.Nm mac_prepare , mac_prepare_file_label , +.Nm mac_prepare , mac_prepare_type , mac_prepare_file_label , .Nm mac_prepare_ifnet_label , mac_prepare_process_label .Nd allocate appropriate storage for .Vt mac_t .Sh SYNOPSIS .In security/mac.h .Ft int -.Fn mac_prepare "mac_t *mac" "char *elements" +.Fn mac_prepare "mac_t *mac" "const char *elements" +.Ft int +.Fn mac_prepare_type "mac_t *mac" "const char *name" .Ft int .Fn mac_prepare_file_label "mac_t *mac" .Ft int @@ -55,21 +57,46 @@ .Fa *mac for use by .Xr mac_get 3 . +When the resulting label is passed into the +.Xr mac_get 3 +functions, the kernel will attempt to fill in the label elements specified +when the label was prepared. +Elements are specified in a nul-terminated string, using commas to +delimit fields. +Element names may be prefixed with the +.Dv ? +character to indicate that a failure by the kernel to retrieve that +element should not be considered fatal. .Pp The .Fn mac_prepare function accepts a list of policy names as a parameter, and allocates the storage to fit those label elements accordingly. +The remaining functions in the family make use of system defaults defined +in +.Xr mac.conf 5 +instead of an explicit +.Va elements +argument, deriving the default from the specified object type. .Pp +.Fn mac_prepare_type +allocates the storage to fit an object label of the type specified by +the +.Va name +argument. The .Fn mac_prepare_file_label , .Fn mac_prepare_ifnet_label , and .Fn mac_prepare_process_label -functions allocate the storage to fit file, network interface, -and process labels, respectively. -The default label elements employed by these APIs is configured in -.Xr mac.conf 5 . +functions are equivalent to invocations of +.Fn mac_prepare_type +with arguments of +.Qq file , +.Qq ifnet , +and +.Qq process +respectively. .Sh RETURN VALUES .Rv -std .Sh SEE ALSO ==== //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_set.3#2 (text+ko) ==== @@ -28,7 +28,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libc/posix1e/mac_set.3,v 1.8 2003/01/15 03:02:30 chris Exp $ +.\" $FreeBSD: src/lib/libc/posix1e/mac_set.3,v 1.10 2003/11/16 20:21:21 rwatson Exp $ .\" .Dd January 14, 2003 .Dt MAC_SET 3 @@ -61,26 +61,27 @@ functions associate a MAC label specified by .Fa label -to the file referenced to by -.Fa path_p , +with the file referenced by +.Fa path , or to the file descriptor .Fa fd , respectively. -Note that this function will fail on socket descriptors. -For information on -setting MAC labels on socket descriptors see -.Xr setsockopt 2 . The .Fn mac_set_link function is the same as .Fn mac_set_file , except that it does not follow symlinks. +Note that when a file descriptor references a socket, label operations +on the file descriptor act on the socket, not on the file that may +have been used as a rendezvous when binding the socket. +.Pp The .Fn mac_set_lctx function associates the MAC label specified by .Fa label with the login context the current process is a member of, if any. +.Pp The .Fn mac_set_proc function associates the MAC label @@ -108,7 +109,9 @@ The .Fa label argument -is not a valid MAC label. +is not a valid MAC label, or the object referenced by +.Fa fd +is not appropriate for label operations. .It Bq Er EOPNOTSUPP Setting MAC labels is not supported by the file referenced by @@ -122,7 +125,7 @@ .It Bq Er ENAMETOOLONG .\" XXX POSIX_NO_TRUNC? The length of the pathname in -.Fa path_p +.Fa path exceeds .Dv PATH_MAX , or a component of the pathname @@ -130,12 +133,12 @@ .Dv NAME_MAX . .It Bq Er ENOENT The file referenced by -.Fa path_p +.Fa path does not exist. .It Bq Er ENOTDIR A component of the pathname referenced by -.Fa path_p +.Fa path is not a directory. .El .Sh SEE ALSO ==== //depot/projects/trustedbsd/sedarwin8/darwin/libmac/mac_text.3#2 (text+ko) ==== @@ -28,7 +28,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libc/posix1e/mac_text.3,v 1.8 2003/01/15 03:01:45 chris Exp $ +.\" $FreeBSD: src/lib/libc/posix1e/mac_text.3,v 1.11 2004/06/30 20:09:09 ru Exp $ .\" .Dd December 21, 2001 .Dt MAC_TEXT 3 @@ -54,7 +54,7 @@ and places it in .Fa *mac , which must later be freed with -.Xr mac_free 3 . +.Xr free 3 . .Pp The .Fn mac_to_text @@ -72,6 +72,19 @@ POSIX.1e does not define a format for text representations of MAC labels. +.Pp +POSIX.1e requires that text strings allocated using +.Fn mac_to_text +be freed using +.Xr mac_free 3 ; +in the +.Fx +implementation, they must be freed using +.Xr free 3 , +as +.Xr mac_free 3 +is used only to free memory used for type +.Vt mac_t . .Sh ERRORS .Bl -tag -width Er .It Bq Er ENOMEM @@ -79,8 +92,8 @@ to allocate internal storage. .El .Sh SEE ALSO +.Xr free 3 , .Xr mac 3 , -.Xr mac_free 3 , .Xr mac_get 3 , .Xr mac_is_present_np 3 , .Xr mac_prepare 3 ,