PERFORCE change 109989 for review
Todd Miller
millert at FreeBSD.org
Tue Nov 14 20:53:40 UTC 2006
http://perforce.freebsd.org/chv.cgi?CH=109989
Change 109989 by millert at 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 ,
More information about the trustedbsd-cvs
mailing list